# Botpress ADK
Source: https://botpress.com/docs/adk



The Botpress Agent Development Kit (ADK) is a developer-first TypeScript framework for building AI agents on the Botpress Platform.

<Card title="Read the full ADK documentation" href="/adk/introduction" icon="book-open">
  Setup and configuration, conversations, workflows, tools, testing, the Zai LLM utilities, and the CLI reference.
</Card>


# HITL with Desk
Source: https://botpress.com/docs/adk/advanced/desk-hitl

Escalate conversations to support agents in Botpress Desk.

The `desk-hitl` plugin connects your agent to Botpress Desk for human handoff. When escalated, your agent calls `startHitl` to create a Desk ticket and a support agent takes over from there.

<Frame>
  <img alt="Botpress Desk main inbox view" />

  <img alt="Botpress Desk main inbox view" />
</Frame>

## Add `desk-hitl` to your agent

Add the plugin to `agent.config.ts`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { defineConfig, z } from "@botpress/runtime"

export default defineConfig({
  name: "my-agent",

  dependencies: {
    integrations: {
      webchat: "webchat@0.3.0",
    },
    plugins: {
      "desk-hitl": {
        version: "desk-hitl@latest",
      },
    },
  },
})
```

### Customize handoff messages

Override the default messages the plugin sends when an agent joins or a session ends:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
plugins: {
  "desk-hitl": {
    version: "desk-hitl@latest",
    config: {
      agentAssignedMessage: "A support agent has joined the conversation.",
      sessionEndedMessage: "The support session has ended. Is there anything else I can help you with?",
    },
  },
},
```

## Connect your bot in Botpress Desk

To enable escalations, link your bot to Botpress Desk from the Desk UI. This is a one-time step per bot. Your bot must be deployed at least once before it appears in the list.

<Steps>
  <Step>
    Run `adk deploy` to deploy your bot.
  </Step>

  <Step>
    Open [**Botpress Desk**](/docs/desk/introduction).
  </Step>

  <Step>
    Go to **AI Agents → Deflecting Bots**.
  </Step>

  <Step>
    Add your bot.
  </Step>
</Steps>

<Frame>
  <img alt="Deflecting Bots page in Botpress Desk settings" />

  <img alt="Deflecting Bots page in Botpress Desk settings" />
</Frame>

<Warning>
  If you skip this step, `startHitl` will fail with: *"This bot is not connected to Botpress Desk. Enable it on the Deflecting Bots page in Botpress Desk, then republish."*
</Warning>

## Create an escalation tool

Wrap `startHitl` in an `Autonomous.Tool` so the model can decide when to escalate. Create a file called `handToSupport.ts` under `src/tools/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous, context, plugins, z } from "@botpress/runtime"

export default new Autonomous.Tool({
  name: "handToSupport",
  description:
    "Transfer the conversation to a support agent. Use when the user explicitly asks for a support agent, or when their issue is beyond the bot's capabilities.",
  input: z.object({
    reason: z.string().describe("Why the conversation needs a support agent"),
    priority: z.enum(["low", "medium", "high", "urgent"]).default("medium"),
  }),
  handler: async ({ reason, priority }) => {
    const conversation = context.get("conversation")

    await plugins["desk-hitl"].actions.startHitl({
      conversationId: conversation.id,
      title: reason,
      priority,
    })
  },
})
```

Fields passed to `startHitl`:

| Field            | Type                                      | Description                             |
| ---------------- | ----------------------------------------- | --------------------------------------- |
| `conversationId` | `string`                                  | The conversation to escalate — required |
| `title`          | `string`                                  | Ticket title shown in Desk              |
| `priority`       | `'low' \| 'medium' \| 'high' \| 'urgent'` | Ticket priority (default: `'medium'`)   |
| `userName`       | `string`                                  | Customer name shown in the Desk ticket  |
| `userEmail`      | `string`                                  | Customer email shown in the Desk ticket |

## Use the tool in a conversation handler

Add the tool to `conversations/index.ts` and instruct the model when to use it:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import handToSupport from "../tools/handToSupport"

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: `You are a helpful support assistant.
If the user needs help beyond your capabilities or explicitly asks for a support agent, use the handToSupport tool. After calling it, do not send any message.`,
      tools: [handToSupport],
    })
  },
})
```


# Human-in-the-loop (HITL)
Source: https://botpress.com/docs/adk/advanced/hitl

Escalate conversations to live human agents.

<Info>
  This covers the HITL integration and plugin, which works with Botpress's built-in HITL dashboard and external helpdesk platforms (Zendesk, Intercom, etc.). This is separate from [Botpress Desk](/docs/adk/advanced/desk-hitl).
</Info>

HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. It's powered by two dependencies working together: the **HITL integration** (the transport to a helpdesk or agent platform) and the **HITL plugin** (the actions your code calls).

## Add HITL to your agent

Add both the integration and the plugin to `agent.config.ts`. The plugin's `dependencies` block points at the integration by alias:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { defineConfig } from "@botpress/runtime"

export default defineConfig({
  name: "my-agent",

  defaultModels: {
    autonomous: "openai:gpt-4.1-mini-2025-04-14",
    zai: "openai:gpt-4.1-mini-2025-04-14",
  },

  dependencies: {
    integrations: {
      chat: "chat@1.0.0",
      webchat: "webchat@0.3.0",
      hitl: "hitl@2.0.2",
    },

    plugins: {
      hitl: {
        version: "hitl@1.3.0",
        dependencies: {
          hitl: {
            integrationAlias: "hitl",
            integrationInterfaceAlias: "hitl<hitlSession>",
          },
        },
      },
    },
  },
})
```

`integrationAlias` must match a key in `dependencies.integrations`. The ADK validates this at build time, so a typo here fails fast. `integrationInterfaceAlias` tells the plugin which interface entity the integration implements (`hitlSession` for the generic HITL integration, `hitlTicket` for Zendesk, and so on).

The HITL plugin also accepts a top-level `config` object for plugin-wide behavior. See the HITL plugin's Hub listing for the full set of fields.

## Start a handoff

Import `plugins` from `@botpress/runtime` and call `startHitl` from a conversation handler. All inputs are typed against the plugin:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation, plugins } from "@botpress/runtime"

export default new Conversation({
  channel: ["chat.channel", "webchat.channel"],
  handler: async ({ execute, conversation, message }) => {
    if (message.payload.text.toLowerCase() === "/starthitl") {
      await plugins.hitl.actions.startHitl({
        title: "Support HITL",
        description: "Escalate to support agent",
        conversationId: conversation.id,
        userId: message.userId,
        configurationOverrides: {
          onHitlHandoffMessage: "Escalating to support...",
          userHitlCloseCommand: "/end",
          agentAssignedTimeoutSeconds: 100,
        },
      })
      return
    }

    await execute({
      instructions: "You are a helpful assistant. If the user asks for a human, tell them to type /starthitl.",
    })
  },
})
```

The fields passed to `startHitl`:

| Field                    | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| `title`                  | Short label shown to the human agent when the ticket opens            |
| `description`            | Longer context the human agent sees alongside the conversation        |
| `conversationId`         | The conversation to hand off (use `conversation.id` from the handler) |
| `userId`                 | The user initiating the handoff                                       |
| `configurationOverrides` | Optional per-handoff overrides of the plugin config                   |

Common override fields:

| Field                         | Description                                                     |
| ----------------------------- | --------------------------------------------------------------- |
| `onHitlHandoffMessage`        | Message sent to the user when the handoff begins                |
| `userHitlCloseCommand`        | Message text the user can send to close the session             |
| `agentAssignedTimeoutSeconds` | How long to wait for a human agent to pick up before timing out |

For the full set of override fields, see the HITL plugin's Hub listing.

## Use a different provider

The HITL plugin works with any integration that implements the HITL interface. To swap the generic HITL integration for Zendesk, change the integration and update the alias. `hitlTicket` replaces `hitlSession` because Zendesk implements the interface with tickets instead of sessions:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
dependencies: {
  integrations: {
    zendesk: "zendesk@1.0.0",
  },
  plugins: {
    hitl: {
      version: "hitl@1.3.0",
      dependencies: {
        hitl: {
          integrationAlias: "zendesk",
          integrationInterfaceAlias: "hitl<hitlTicket>",
        },
      },
    },
  },
},
```

Your application code doesn't change. `plugins.hitl.actions.startHitl` works the same regardless of which integration is wired underneath.

## Deploy and test

Run `adk deploy` to push the agent to Botpress Cloud. See the [CLI reference](/docs/adk/cli-reference#adk-deploy) for all deploy flags:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk deploy
```

<Warning>
  HITL only works against a deployed bot. `adk dev` downloads the plugin into `bp_modules/` and generates types, but handoffs need the integration's real connection to your helpdesk, which is configured on the production bot.
</Warning>


# Skills
Source: https://botpress.com/docs/adk/ai-native/skills

Give AI coding assistants deep ADK knowledge with installable skills.

Skills are packaged instructions and documentation that teach AI coding assistants how to build with the ADK. When installed, assistants like Claude Code, Cursor, and Codex use them automatically when you ask them to build features, debug issues, write evals, or connect integrations. `adk init` installs them for you alongside your dependencies, so most projects get them out of the box.

## Manual installation

If you need to install skills in an existing project or reinstall them, run the same command `adk init` runs:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npx skills add botpress/skills -s '*' -a codex claude-code -y
```

Use `bunx` instead of `npx` if your project has a `bun.lockb`.

To install a single skill instead of all of them:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npx skills add botpress/skills --skill adk
```

Or install as a Claude Code plugin:

```
/plugin marketplace add botpress/skills
/plugin install adk@botpress-skills
```

## Available skills

| Skill                  | What it teaches                                                                                               | Use when                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **`adk`**              | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK                                |
| **`adk-debugger`**     | Trace reading, log analysis, common failure diagnosis, the debug loop                                         | Bot isn't responding, tools failing, workflows stuck, LLM issues |
| **`adk-evals`**        | Eval file format, all assertion types, CLI usage, per-primitive testing patterns                              | Writing and running automated tests                              |
| **`adk-frontend`**     | Authentication, type generation, client setup, calling bot actions from React/Next.js                         | Building a frontend that connects to your bot                    |
| **`adk-integrations`** | Discovery, adding, configuring, and using integrations end-to-end                                             | Connecting Slack, WhatsApp, Linear, or any integration           |
| **`adk-docs`**         | Documentation standards, creation, review, and maintenance                                                    | Writing or updating docs for your bot                            |

## Slash commands

Skills come with slash commands for Claude Code. Type the command instead of describing what you need:

| Command            | What it does                                            |
| ------------------ | ------------------------------------------------------- |
| `/adk-init`        | Scaffold a new ADK project                              |
| `/adk-debug`       | Debug bot issues using traces, logs, and the debug loop |
| `/adk-eval`        | Write, run, or debug evals                              |
| `/adk-frontend`    | Build frontend apps that integrate with ADK bots        |
| `/adk-integration` | Discover, add, and configure integrations               |
| `/adk-doc-create`  | Create documentation for a feature                      |
| `/adk-doc-review`  | Review project docs for accuracy                        |
| `/adk-doc-update`  | Update docs after code changes                          |
| `/adk-doc-sync`    | Check if docs are in sync with code                     |
| `/adk-doc-search`  | Search project documentation                            |

## MCP server

Skills are the recommended way to give AI assistants ADK knowledge. The ADK also ships an MCP (Model Context Protocol) server that gives assistants live access to your running project, kept here for reference.

Generate the MCP configuration files:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk mcp:init --all
```

This writes config for Claude Code (`.mcp.json`), VS Code (`.vscode/mcp.json`), and Cursor (`.cursor/mcp.json`). See [`adk mcp:init`](/docs/adk/cli-reference#adk-mcpinit) for all flags.

The server exposes these tools:

| Tool                      | What it does                                                       |
| ------------------------- | ------------------------------------------------------------------ |
| `adk_get_agent_info`      | Get project structure and primitives                               |
| `adk_search_integrations` | Search the Botpress Hub                                            |
| `adk_get_integration`     | Get detailed integration info                                      |
| `adk_add_integration`     | Add an integration to the project                                  |
| `adk_send_message`        | Send a test message to the running bot                             |
| `adk_query_traces`        | Query trace spans for debugging                                    |
| `adk_get_dev_logs`        | Get dev server logs and errors                                     |
| `adk_list_workflows`      | List available workflows                                           |
| `adk_start_workflow`      | Start a workflow or get its input schema                           |
| `adk_init_project`        | Scaffold a new ADK project (only available outside an ADK project) |


# CLI reference
Source: https://botpress.com/docs/adk/cli-reference

All commands and flags available with the ADK CLI.

The `adk` CLI is how you scaffold, run, deploy, and debug ADK agents. Run `adk --help` for the top-level command list, or `adk <command> --help` for flags on a specific command.

## Global flags

These flags work with every command:

| Flag                  | Description                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `--help`, `-h`        | Show help information                                                                                 |
| `--version`, `-V`     | Show version number                                                                                   |
| `--no-cache`          | Disable caching for integration lookups                                                               |
| `--profile <profile>` | Credentials profile to use (overrides the `ADK_PROFILE` environment variable and the current profile) |

Most commands also accept `--format json` for machine-readable output. The following commands don't: `dev`, `login`, `profiles list`, `profiles set`, `upgrade`, `remove`, `self-upgrade`, `telemetry`, `theme`, `mcp`, `mcp:init`, `run`, `assets pull`.

## Project

These commands manage an agent project from scaffold to deploy:

| Command           | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `adk init [name]` | Initialize a new project                                  |
| `adk dev`         | Start development mode with hot reloading                 |
| `adk build`       | Build the agent for production                            |
| `adk deploy`      | Deploy the agent to Botpress Cloud                        |
| `adk check`       | Validate project structure and config (no login required) |
| `adk status`      | Show project status, integrations, and server state       |
| `adk link`        | Link local agent to a workspace and bot                   |

### `adk init`

Scaffold a new agent project. Pass a name, or omit it to be prompted:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk init my-agent
adk init my-agent --template hello-world
adk init --list-templates
```

| Flag                        | Description                        |
| --------------------------- | ---------------------------------- |
| `-t, --template <template>` | Template to use (default: `blank`) |
| `-y, --yes`, `--defaults`   | Skip prompts, use defaults         |
| `--skip-link`               | Skip the linking step              |
| `--list-templates`          | List available templates and exit  |

### `adk dev`

Start the dev server with hot reload:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk dev
adk dev --port 3000 --port-console 3001
```

| Flag                    | Description                                            | Default |
| ----------------------- | ------------------------------------------------------ | ------- |
| `-p, --port <port>`     | Bot server port                                        | `3000`  |
| `--port-console <port>` | Dev console port                                       | `3001`  |
| `--otlp`                | Enable OTLP export to external collector (port `4318`) |         |
| `--port-otlp <port>`    | Override the OTLP collector endpoint port              |         |
| `-v, --verbose`         | Show additional details                                |         |
| `--non-interactive`     | Emit structured NDJSON events to stdout                |         |

### `adk deploy`

Deploy the built agent to Botpress Cloud:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk deploy
adk deploy -y
```

| Flag                      | Description                    | Default      |
| ------------------------- | ------------------------------ | ------------ |
| `-e, --env <environment>` | Deployment environment         | `production` |
| `-y, --yes`               | Auto-approve preflight changes |              |

### `adk link`

Link the local agent to a workspace and bot. Writes to `agent.json`, or to `agent.local.json` with `--local`:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk link
adk link --workspace wkspace_123 --bot bot_456
```

| Flag               | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `--workspace <id>` | Workspace ID                                                     |
| `--bot <id>`       | Bot ID to link to                                                |
| `--dev <id>`       | Dev bot ID                                                       |
| `--api-url <url>`  | Botpress API URL                                                 |
| `-f, --force`      | Overwrite existing `agent.json`                                  |
| `--local`          | Write to gitignored `agent.local.json` (for multi-dev workflows) |

## Integrations

These commands add, inspect, and manage the integrations your agent depends on:

| Command                     | Description                                               |
| --------------------------- | --------------------------------------------------------- |
| `adk add <resource>`        | Add an integration or interface (aliases: `i`, `install`) |
| `adk remove [resource]`     | Remove an integration, interface, or plugin (alias: `rm`) |
| `adk upgrade [integration]` | Upgrade integration(s) to latest version (alias: `up`)    |
| `adk search <query>`        | Search the Botpress Hub                                   |
| `adk list`                  | List installed integrations                               |
| `adk info <name>`           | Show detailed integration info                            |

### `adk add`

Add an integration or interface to your agent. Accepts a name, `workspace/name`, or a specific version:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk add webchat
adk add slack@latest
adk add slack@0.5.0
adk add my-workspace/custom@1.0.0
adk add interface:translator@1.0.0
adk add webchat --alias custom-webchat
```

| Flag              | Description                   |
| ----------------- | ----------------------------- |
| `--alias <alias>` | Custom alias for the resource |

### `adk search`

Search the Botpress Hub for integrations:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk search crm
adk search slack --limit 5
```

| Flag               | Description           | Default |
| ------------------ | --------------------- | ------- |
| `--limit <number>` | Max results to return | `20`    |

### `adk list`

List integrations in your project, or all available ones on the Hub:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk list
adk list --available
```

| Flag          | Description                                          | Default |
| ------------- | ---------------------------------------------------- | ------- |
| `--available` | List all available integrations (not just installed) |         |
| `--limit <n>` | Max results                                          | `50`    |

### `adk info`

Show details for a specific integration. Filter by a single facet or show the full spec:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk info slack
adk info slack --actions
adk info slack --full
```

| Flag         | Description        |
| ------------ | ------------------ |
| `--actions`  | Show only actions  |
| `--channels` | Show only channels |
| `--events`   | Show only events   |
| `--full`     | Show all details   |

## Configuration and secrets

These commands manage config values and secrets:

| Command                        | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `adk config`                   | Validate and fill missing config values interactively |
| `adk config:get <key>`         | Get a configuration value                             |
| `adk config:set <key> <value>` | Set a configuration value                             |
| `adk secret`                   | Show declared secrets and their status                |
| `adk secret:set <key> <value>` | Set a secret value                                    |
| `adk secret:delete <key>`      | Delete a secret                                       |
| `adk models`                   | List available LLM models                             |

All configuration and secret commands accept `--prod` to target the production environment instead of dev.

## Chat and testing

These commands let you send messages to your agent and run eval suites:

| Command                  | Description                      |
| ------------------------ | -------------------------------- |
| `adk chat`               | Interactive chat with your agent |
| `adk evals [name]`       | Run eval suites                  |
| `adk evals runs [runId]` | List or show eval run history    |

### `adk chat`

Open an interactive chat, or send a single message with `--single`. Requires `adk dev` to be running:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk chat
adk chat --single "What's the status of order 12345?"
adk chat --single "Follow up" --conversation-id <id>
```

| Flag                     | Description               | Default |
| ------------------------ | ------------------------- | ------- |
| `--single <message>`     | Send one message and exit |         |
| `--conversation-id <id>` | Continue a conversation   |         |
| `--timeout <duration>`   | Max wait duration         | `60s`   |

### `adk evals`

Run eval suites. With no arguments, runs all evals; pass a name to run just one:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk evals
adk evals greeting
adk evals --tag smoke
adk evals --type regression
adk evals -v
```

| Flag                    | Description                                 | Default                 |
| ----------------------- | ------------------------------------------- | ----------------------- |
| `--tag <tag>`           | Run only evals with this tag                |                         |
| `--type <type>`         | Run only `capability` or `regression` evals |                         |
| `--judge-model <model>` | Model for `llm_judge` assertions            |                         |
| `-v, --verbose`         | Show full details for all evals             |                         |
| `--server <url>`        | Dev server URL                              | `http://localhost:3001` |

### `adk evals runs`

List past eval runs, or show the details of a specific one:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk evals runs
adk evals runs --latest
adk evals runs <run-id> -v
```

| Flag            | Description         | Default |
| --------------- | ------------------- | ------- |
| `--latest`      | Show the latest run |         |
| `--limit <n>`   | Max runs to list    | `10`    |
| `-v, --verbose` | Show full details   |         |

## Workflows

These commands discover and run workflows against the local dev server:

| Command                              | Description                            |
| ------------------------------------ | -------------------------------------- |
| `adk workflows`                      | List all discovered workflows          |
| `adk workflows inspect <name>`       | Inspect a workflow schema and metadata |
| `adk workflows run <name> [payload]` | Run a workflow                         |

### `adk workflows run`

Run a workflow with a JSON payload. Add `--wait` to block until it finishes:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk workflows run onboarding '{"userId":"123"}'
adk workflows run onboarding '{"userId":"123"}' --wait --timeout 30s
```

| Flag                   | Description                          |
| ---------------------- | ------------------------------------ |
| `--wait`               | Wait for the workflow to finish      |
| `--timeout <duration>` | Max wait duration (implies `--wait`) |

## Debugging

These commands help you inspect what your agent is doing:

| Command                      | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `adk logs [tokens...]`       | Query dev server logs                        |
| `adk traces [tokens...]`     | Query trace data                             |
| `adk run <script> [args...]` | Run a TypeScript script with the ADK runtime |

### `adk logs`

Query logs from `.adk/logs/`. Pass filter tokens as positional arguments, or stream with `--follow`:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk logs
adk logs error
adk logs warning since=1h
adk logs --follow
adk logs --follow limit=10
```

| Token              | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `error`            | Show errors only                                          |
| `warning`          | Show errors + warnings                                    |
| `info`             | Show errors + warnings + info                             |
| `since=<duration>` | Only entries newer than duration (e.g. `30s`, `5m`, `1h`) |
| `limit=<n>`        | Max entries to show (default: `50`)                       |

| Flag           | Description                                           |
| -------------- | ----------------------------------------------------- |
| `-f, --follow` | Stream logs in real time                              |
| `--summary`    | Emit a single JSON summary (requires `--format json`) |

### `adk traces`

Query trace data from the local store. Filter tokens narrow by workflow, action, trigger, or drill into a specific trace:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk traces
adk traces error
adk traces since=1h
adk traces workflow=onboarding
adk traces trace=<id>
adk traces trace=<id> --include-llm
adk traces --follow
```

| Token               | Description                        |
| ------------------- | ---------------------------------- |
| `error`             | Show only error traces             |
| `workflow=<name>`   | Filter by workflow name            |
| `action=<name>`     | Filter by action/tool name         |
| `trigger=<name>`    | Filter by trigger name             |
| `conversation=<id>` | Filter by conversation ID          |
| `trace=<id>`        | Drill into a specific trace        |
| `since=<duration>`  | Only traces newer than duration    |
| `until=<duration>`  | Only traces older than duration    |
| `limit=<n>`         | Max traces to show (default: `20`) |

| Flag            | Description                                        |
| --------------- | -------------------------------------------------- |
| `-f, --follow`  | Stream new traces                                  |
| `--include-llm` | Include LLM instructions and code in drill-in mode |

### `adk run`

Run a TypeScript script with the full ADK runtime, so you can import actions, Zai, and tables directly:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk run scripts/migrate.ts
adk run scripts/seed.ts --prod
adk run scripts/process.ts arg1 arg2
```

| Flag          | Description                           |
| ------------- | ------------------------------------- |
| `-f, --force` | Force regeneration of the bot project |
| `--prod`      | Use production bot (default: dev)     |

## Knowledge bases

Sync local knowledge base content with Botpress:

| Command       | Description                               |
| ------------- | ----------------------------------------- |
| `adk kb sync` | Synchronize knowledge bases with Botpress |

### `adk kb sync`

Push local KB sources to the dev or prod bot. Use `--dry-run` to preview changes first:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk kb sync --dev
adk kb sync --prod
adk kb sync --prod --force
adk kb sync --dry-run
```

| Flag        | Description                       |
| ----------- | --------------------------------- |
| `--dev`     | Sync with development bot         |
| `--prod`    | Sync with production bot          |
| `--dry-run` | Preview changes without applying  |
| `-y, --yes` | Skip confirmation prompts         |
| `--force`   | Force re-sync all knowledge bases |

## Assets

Manage static files your agent serves or references:

| Command             | Description                               |
| ------------------- | ----------------------------------------- |
| `adk assets sync`   | Synchronize assets with remote storage    |
| `adk assets list`   | List all asset files                      |
| `adk assets status` | Show asset sync status                    |
| `adk assets pull`   | Download remote assets to local directory |

### `adk assets sync`

Upload local assets to remote storage. Use `--dry-run` to see what would change:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk assets sync
adk assets sync --dry-run
adk assets sync --force -y
```

| Flag                | Description                      |
| ------------------- | -------------------------------- |
| `--dry-run`         | Preview changes without applying |
| `-y, --yes`         | Skip confirmation prompts        |
| `--bail-on-failure` | Stop on first error              |
| `--force`           | Force re-upload all files        |

### `adk assets list`

List asset files. By default shows both local and remote; filter with `--local` or `--remote`:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk assets list
adk assets list --local
adk assets list --remote
```

| Flag       | Description             |
| ---------- | ----------------------- |
| `--local`  | Show only local assets  |
| `--remote` | Show only remote assets |

## AI assistants

These commands integrate the ADK with AI coding tools:

| Command        | Description                      |
| -------------- | -------------------------------- |
| `adk mcp`      | Start the MCP server             |
| `adk mcp:init` | Generate MCP configuration files |

### `adk mcp`

Start the MCP server so tools like Claude Code, Cursor, or VS Code can talk to your running dev server:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk mcp
adk mcp --port 3001
```

| Flag            | Description                          | Default |
| --------------- | ------------------------------------ | ------- |
| `--cwd <path>`  | Working directory for MCP operations |         |
| `--port <port>` | UI server port to connect to         | `3001`  |

### `adk mcp:init`

Generate MCP configuration files for supported AI assistants:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk mcp:init --all
adk mcp:init --tool claude-code
adk mcp:init --tool vscode cursor
```

| Flag                   | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `--tool <tool...>`     | Specific tool(s): `claude-code`, `vscode`, `cursor` |
| `--all`                | Generate for all supported tools                    |
| `--force`              | Overwrite existing config                           |
| `--project-dir <path>` | ADK project subdirectory (for monorepos)            |

## Account

These commands manage your Botpress credentials and the CLI itself:

| Command                      | Description                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| `adk login`                  | Authenticate with Botpress                                             |
| `adk profiles list`          | List authentication profiles                                           |
| `adk profiles set [profile]` | Switch to a different profile                                          |
| `adk self-upgrade [tag]`     | Upgrade ADK CLI to latest (or specific) version (alias: `self-update`) |
| `adk telemetry`              | Manage telemetry preferences                                           |
| `adk theme`                  | Manage CLI theme (dark/light)                                          |

### `adk login`

Authenticate with your Botpress account. Pass `--token` to skip the browser flow:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk login
adk login --token <token>
adk login --profile staging
```

| Flag                  | Description                            | Default                      |
| --------------------- | -------------------------------------- | ---------------------------- |
| `--token <token>`     | Botpress API token                     |                              |
| `--profile <profile>` | Profile name to save credentials under |                              |
| `--api-url <url>`     | Botpress API URL                       | `https://api.botpress.cloud` |

### `adk self-upgrade`

Upgrade the ADK CLI. Pass a tag (`beta`, `next`) or an explicit version:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk self-upgrade
adk self-upgrade beta
adk self-upgrade 1.18.0
```

### `adk telemetry`

View or change telemetry preferences. With no flags, prints the current status:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk telemetry
adk telemetry --enable
adk telemetry --disable
```

| Flag        | Description           |
| ----------- | --------------------- |
| `--status`  | Show telemetry status |
| `--enable`  | Enable telemetry      |
| `--disable` | Disable telemetry     |

### `adk theme`

Switch the CLI theme between dark and light:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk theme --set dark
adk theme --set light
```

| Flag            | Description                   |
| --------------- | ----------------------------- |
| `--set <theme>` | Set theme (`dark` or `light`) |


# Run AI agents in a conversation
Source: https://botpress.com/docs/adk/conversations/ai-execution

Use `execute()` to hand messages to the AI model.

The `execute()` function is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code.

The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (which defaults to 10 and is configurable).

The `await` resolves once the loop finishes.

<Note>
  Under the hood, `execute()` is powered by [LLMz](https://github.com/botpress/botpress/tree/master/packages/llmz).
</Note>

## Basic usage

```typescript highlight={4-6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful customer support agent.",
    })
  },
})
```

The model reads the full conversation transcript, follows your instructions, and responds. If tools are available, it can call them before responding.

## Instructions

Pass instructions into the `instructions` field to tell the model how to behave. They can be a static string or a function that returns a string:

```typescript highlight={3, 8-13} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// String
await execute({
  instructions: "You are a helpful assistant that speaks formally.",
})

// Function that returns a string
await execute({
  instructions: () => {
    const hour = new Date().getHours()
    return hour < 12
      ? "You are a cheerful morning assistant."
      : "You are a calm evening assistant."
  },
})
```

Instructions are evaluated fresh on each execution. Use a function when you need dynamic behavior based on state, time, or other context.

## Knowledge

Pass knowledge bases into the `knowledge` field to give the model access to your documents:

```typescript highlight={6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { DocsKB } from "../knowledge/docs"
import { FaqKB } from "../knowledge/faq"

await execute({
  instructions: "Answer questions using the documentation.",
  knowledge: [DocsKB, FaqKB],
})
```

The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents.

<Tip>
  For more information on defining knowledge bases, check out the [Knowledge base documentation](/docs/adk/data/knowledge).
</Tip>

## Tools

Give the model functions it can call by passing them into the `tools` field:

```typescript highlight={6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { getWeather } from "../tools/weather"
import { createTicket } from "../tools/ticket"

await execute({
  instructions: "You are a helpful assistant.",
  tools: [getWeather, createTicket],
})
```

The model decides when to call a tool based on the conversation. For a full guide on defining tools, see [Define Tools](/docs/adk/conversations/tools).

## Exits

Pass in `exits` to let the model end execution with a structured result:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous, z } from "@botpress/runtime"

const handoff = new Autonomous.Exit({
  name: "handoffToHuman",
  description: "Transfer the conversation to a human agent",
  schema: z.object({
    reason: z.string(),
    priority: z.enum(["low", "medium", "high"]),
  }),
})

const result = await execute({
  instructions: "Help the user. If you can't resolve their issue, hand off to a human.",
  exits: [handoff],
})

if (result.exit?.name === "handoffToHuman") {
  const { reason, priority } = result.exit.value
  // Route to human agent
}
```

## Model override

You can override the default model for a specific execution:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  model: "openai:gpt-4.1-2025-04-14",
  instructions: "You are a helpful assistant.",
})
```

You can also pass an array for fallback:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  model: ["cerebras:gpt-oss-120b", "openai:gpt-4.1-2025-04-14"],
  instructions: "You are a helpful assistant.",
})
```

The default model is set in `agent.config.ts` under `defaultModels.autonomous`. You can also browse and change models from the dev console under **Settings > LLM Config**.

## Temperature and reasoning

To control the model's temperature and reasoning effort, use the `temperature` and `reasoningEffort` props:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  instructions: "You are a helpful assistant.",
  temperature: 0.3,
  reasoningEffort: "high",
})
```

| Option            | Default | Description                                                                                      |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `temperature`     | `0.7`   | Controls randomness. Lower is more deterministic.                                                |
| `reasoningEffort` | none    | `"low"`, `"medium"`, `"high"`, `"dynamic"`, or `"none"`. Only for models that support reasoning. |

## Iterations

The model can loop multiple times in a single execution (e.g., call a tool, read the result, call another tool, then respond). The `iterations` prop controls the maximum number of loops:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  instructions: "You are a research assistant.",
  iterations: 20,
})
```

The number of iterations defaults to 10 and is clamped between 1 and 100.

## Cancellation

Pass an `AbortSignal` to cancel execution mid-loop. Useful when the caller needs to bail out (e.g. a timeout or the user navigating away):

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const controller = new AbortController()

setTimeout(() => controller.abort(), 30_000)

await execute({
  instructions: "You are a helpful assistant.",
  signal: controller.signal,
})
```

## Mode

Execution runs in `chat` mode by default, where the model sends messages to the user. You can switch to `worker` mode for background processing:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  mode: "worker",
  instructions: "Analyze the data and update the cart object.",
  objects: [cart],
})
```

In worker mode, the model executes without sending messages to the conversation.

## Hooks

Hooks let you observe and intercept execution at key moments:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  instructions: "You are a helpful assistant.",
  hooks: {
    onBeforeTool: async ({ tool, input, controller }) => {
      console.log(`Calling tool: ${tool.name}`, input)
      // Return { input: modifiedInput } to change the input
      // Call controller.abort() to cancel the tool call
    },

    onAfterTool: async ({ tool, input, output }) => {
      console.log(`Tool ${tool.name} returned:`, output)
      // Return { output: modifiedOutput } to change the output
    },

    onTrace: ({ trace, iteration }) => {
      // Log or monitor execution traces
    },

    onIterationStart: async (iteration, controller, context) => {
      // Runs before each iteration
    },

    onIterationEnd: async (iteration, controller) => {
      // Runs after each iteration
      // Use controller to stop execution early
    },

    onBeforeExecution: async (iteration, controller) => {
      // Runs before code execution
      // Return { code: modifiedCode } to change what gets executed
    },

    onExit: async (result) => {
      // Runs when the model triggers an exit
    },
  },
})
```

## Debugging execution

To see exactly what happened during an execution (which tools were called, what the model generated, how many iterations it took, and any errors), see [Debug with logs and traces](/docs/adk/testing/debugging).

<Frame>
  <img alt="Traces view in dev console" />

  <img alt="Traces view in dev console" />
</Frame>


# Use custom components
Source: https://botpress.com/docs/adk/conversations/custom-components

Build and render custom React UI inside Webchat.

Custom components let you render your own React UI inside [Webchat](/docs/webchat/get-started/introduction). Instead of being limited to text, images, and carousels, you can build any visual element and have either your code or the LLM send it to users.

There are two ways to use custom components:

1. **Direct send** - your handler explicitly sends the component
2. **LLM-driven** - the LLM decides when to render the component during `execute()`

## Creating a component

A custom component has two files: a React component (`.bp.tsx`) and an ADK wrapper (`.ts`).

### Step 1: Write the React component

Create a `.bp.tsx` file in `src/components/`:

```tsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// src/components/TicketCard.bp.tsx
import React from "react"

type Props = {
  ticketId: string
  title: string
  priority: "low" | "medium" | "high" | "urgent"
  ticketStatus: string
}

const TicketCard: React.FC<Props> = ({ ticketId, title, priority, ticketStatus }) => {
  return (
    <div style={{
      border: "1px solid #e5e7eb",
      borderRadius: 10,
      padding: "14px 16px",
      background: "#fff",
      maxWidth: 360,
    }}>
      <div style={{ fontWeight: 600, fontSize: 14 }}>{ticketId}</div>
      <div style={{ fontSize: 14, color: "#111827", marginTop: 4 }}>{title}</div>
      <div style={{ fontSize: 12, color: "#6b7280", marginTop: 4 }}>
        {priority} - {ticketStatus}
      </div>
    </div>
  )
}

export default TicketCard
```

You can use inline styles or import `.css` files directly. CSS imports are bundled and injected as `<style>` tags at runtime. React 18 is available with hooks like `useState`, `useMemo`, and `useEffect`.

### Step 2: Create the ADK wrapper

Create a `.ts` file next to the `.bp.tsx`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// src/components/TicketCard.ts
import { CustomComponent } from "@botpress/runtime"
import component from "./TicketCard.bp.tsx"

export const TicketCardComponent = new CustomComponent(component)
```

The component is now discoverable by `adk dev` and `adk deploy`. The component name is derived from the React function name (`TicketCard` in this case).

## Sending components manually

Send a custom component like any other message:

```typescript highlight={7-18} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import { TicketCardComponent } from "../components/TicketCard"

export default new Conversation({
  channel: ["webchat.channel"],
  handler: async ({ conversation }) => {
    await conversation.send({
      type: "customComponent",
      payload: {
        component: TicketCardComponent,
        props: {
          ticketId: "TKT-001",
          title: "VPN not connecting",
          priority: "high",
          ticketStatus: "open",
        },
      },
    })
  },
})
```

The `props` object is type-checked against the React component's `Props` type.

## LLM-driven components

To let the LLM decide when to render your component, add LLM metadata and list it in the conversation's `components` array.

### Add LLM metadata

The `description` field tells the LLM what the component does:

```typescript title="TicketCard.ts" highlight={5-6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { CustomComponent, z } from "@botpress/runtime"
import component from "./TicketCard.bp.tsx"

export const TicketCardComponent = new CustomComponent(component, {
  description:
    "Display a ticket summary card. Use this after creating or looking up a ticket.",
  props: z.object({
    ticketId: z.string().describe("The ticket ID"),
    title: z.string().describe("Short summary of the issue"),
    priority: z.enum(["low", "medium", "high", "urgent"]).describe("Priority level"),
    ticketStatus: z.string().describe("Current ticket status"),
  }),
  exampleValues: [
    { ticketId: "TKT-001", title: "VPN not working", priority: "high", ticketStatus: "open" },
  ],
})
```

| Field           | Required | Description                                                                 |
| --------------- | -------- | --------------------------------------------------------------------------- |
| `description`   | Yes      | Tells the LLM when to use this component. Be specific.                      |
| `props`         | Yes      | Zod schema defining the component's props. Use `.describe()` on each field. |
| `exampleValues` | Yes      | Array of example prop objects. Converted to JSX examples in the LLM prompt. |

### Provide the component to the LLM

To provide the component to your agent's LLM, pass it into the `execute()` function's `components` field:

```typescript highlight={6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import { TicketCardComponent } from "../components/TicketCard"

export default new Conversation({
  channel: ["webchat.channel"],
  components: [TicketCardComponent],
  handler: async ({ execute }) => {
    await execute({
      instructions:
        "You are an IT support assistant. When a user reports an issue, create a ticket and display it using the TicketCard component.",
    })
  },
})
```

The LLM now knows about `<TicketCard>` and will render it when appropriate during `execute()`.

<Note>
  If you list a component in `components` that was created without LLM metadata, the `Conversation` constructor throws immediately.
</Note>

## Combining both approaches

You can use direct send and LLM-driven components in the same conversation:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import { TicketCardComponent } from "../components/TicketCard"
import { WelcomeBannerComponent } from "../components/WelcomeBanner"

export default new Conversation({
  channel: ["webchat.channel"],
  events: ["webchat:conversationStarted"],
  components: [TicketCardComponent],
  handler: async ({ execute, type, event, conversation }) => {
    if (event?.type === "webchat:conversationStarted") {
      await conversation.send({
        type: "customComponent",
        payload: { component: WelcomeBannerComponent, props: {} },
      })
      return
    }

    await execute({
      instructions: "You are an IT support assistant...",
    })
  },
})
```

`WelcomeBannerComponent` doesn't need LLM metadata since it's only sent directly. It's not in the `components` array.

## Build pipeline

During `adk dev` and `adk deploy`, custom components go through the following pipeline:

1. **Discover** - scans `src/` for `.ts` files that export `CustomComponent` instances
2. **Resolve** - finds the `.bp.tsx` import in each wrapper
3. **Bundle** - `esbuild` bundles the `.bp.tsx` into standalone ESM (`react` and `react-dom` are externalized)
4. **Upload** - the bundle is uploaded to Botpress as a public file
5. **Wire** - the component URL is injected so `conversation.send()` works

During `adk dev`, the file watcher rebuilds only changed components incrementally.

## Tips

* **Keep components focused.** One component, one purpose. A ticket card, a status badge, a product listing.
* **Use `useMemo`** for expensive computations or random values. React may re-render multiple times.
* **Name your component function.** The name is derived from the function name. Anonymous exports become `"UnnamedComponent"`.
* **Write good descriptions.** The LLM reads the `description` field to decide when to use the component.
* **Provide realistic examples.** Use values that represent real usage, not placeholders like `"string"`.
* **Avoid reserved prop names.** The webchat renderer reserves `status`. Use more specific names like `ticketStatus`.

## Limitations

* **Webchat only.** Custom components only render in Webchat. Other channels don't support them.
* **No global stylesheets.** You can import `.css` files in your component, but your project's global styles are not available.
* **React 18.** React 19 features are not available.
* **No server-side rendering.** Components are client-rendered in the browser.

## Troubleshooting

| Problem                                         | Cause                                         | Fix                                                                               |
| ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
| `Component "X" not deployed. Run "adk deploy".` | Component URL not set                         | Re-run `adk dev` to build and upload                                              |
| Component doesn't appear in Webchat             | Wrapper doesn't export a `CustomComponent`    | Check the `.ts` file imports the `.bp.tsx` and exports `new CustomComponent(...)` |
| LLM never uses the component                    | Missing metadata or not in `components` array | Add `{ description, props, exampleValues }` and list in `components`              |
| Styles look wrong                               | Using CSS classes                             | Switch to inline styles                                                           |
| A prop is `undefined`                           | Reserved prop name (e.g., `status`)           | Rename to something specific (e.g., `ticketStatus`)                               |
| TypeScript errors on `.bp.tsx`                  | Missing `tsconfig` settings                   | Add `"jsx": "react"`, `"allowImportingTsExtensions": true`, and `"noEmit": true`  |


# Manage conversation lifecycle
Source: https://botpress.com/docs/adk/conversations/lifecycle

Configure nudges, expiration, and session management for conversations.

Lifecycle management adds idle nudges and session expiration to your conversations. You configure timers, and the framework handles scheduling, state resets, and session tracking.

## Basic setup

Add a `lifecycle` prop to your conversation:

```typescript highlight={10-13} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import { z } from "@botpress/sdk"

export default new Conversation({
  channel: "webchat.channel",
  state: z.object({
    topic: z.string().optional(),
  }),

  lifecycle: {
    nudge: { after: "5m", interval: "10m", max: 3 },
    expire: { after: "30m" },
  },

  handler: async (props) => {
    if (props.type === "nudge") {
      await props.conversation.send({
        type: "text",
        payload: { text: "Still there? Let me know if you need anything." },
      })
      return
    }

    if (props.type === "expire") {
      await props.conversation.send({
        type: "text",
        payload: { text: "Closing this session due to inactivity. Come back anytime!" },
      })
      return
    }

    await props.execute({ instructions: "You are a helpful assistant." })
  },
})
```

## Concepts

### Nudge

A nudge is an automated reminder sent when the user has been silent for a configured duration. Nudges are:

* **Configurable** - you set when the first one fires (`after`), how often to repeat (`interval`, defaults to `after` if omitted), and when to stop (`max`, unlimited if omitted)
* **Auto-resetting** - any user message resets the nudge timer
* **Handler-controlled** - the framework decides when to nudge, you decide what to say
* **Workflow-aware** - nudges are automatically suppressed while a workflow is running

### Expiration

Expiration is when a conversation session ends due to prolonged inactivity. When it fires:

1. Your handler runs first (`type: "expire"`) so you can send a goodbye message or save a summary
2. Then the framework takes over: cancels workflows, tags the conversation, resets state, clears the transcript

### Session

A session is a single period of activity within a conversation. One conversation can have many sessions over its lifetime. The framework manages a `session` object automatically:

| Field            | Type                      | Description                                                                                |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
| `id`             | `string`                  | Unique identifier for this session. Changes on every expiration.                           |
| `number`         | `number`                  | Monotonically increasing counter. Session 1, 2, 3...                                       |
| `status`         | `'active'` or `'expired'` | Whether this session is currently live.                                                    |
| `startedAt`      | `string`                  | ISO timestamp when this session began.                                                     |
| `lastActivityAt` | `string`                  | ISO timestamp of the last user message.                                                    |
| `nudgeCount`     | `number`                  | How many nudges have fired in this session. Resets on new activity and on session renewal. |

You can access the current session via `conversation.session`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const session = props.conversation.session

if (session) {
  console.log(`Session #${session.number}, status: ${session.status}`)
}
```

The `session` object is read-only. It returns `undefined` for conversations without lifecycle configured.

## What happens when a conversation expires

```mermaid theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
flowchart TD
    A["Expire timer fires"] --> B{"Race guard check:<br/>user sent a message<br/>after this was scheduled?"}
    B -- Yes --> C["Skip silently,<br/>timers already rescheduled"]
    B -- No --> D["Your handler runs<br/>(type: expire)"]
    D --> E["Framework cleanup:<br/>1. Cancel active workflows<br/>2. Cancel pending nudge<br/>3. Set session status = expired<br/>4. Tag conversation<br/>5. Reset user state<br/>6. Clear LLM transcript"]
    E --> F["Done. Next message<br/>triggers session renewal."]
```

## Duration strings

Lifecycle durations use `ms`-compatible strings:

| String  | Duration   |
| ------- | ---------- |
| `'30s'` | 30 seconds |
| `'5m'`  | 5 minutes  |
| `'1h'`  | 1 hour     |
| `'24h'` | 24 hours   |
| `'2d'`  | 2 days     |

Durations are validated at construction time. Invalid or non-positive values throw an error immediately.

## Common patterns

### Escalating nudges

Use `nudgeCount` to change the tone as nudges progress:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (props.type === "nudge") {
  const session = props.conversation.session!
  const messages = [
    "Still there? Take your time.",
    "Just checking in. Do you need help with anything?",
    "I'll close this session soon if you don't need anything else.",
  ]
  const text = messages[session.nudgeCount - 1] ?? messages[messages.length - 1]
  await props.conversation.send({ type: "text", payload: { text } })
  return
}
```

### Welcome back after expiration

Detect when a user returns after a session expired:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (props.type === "message" && props.conversation.session?.number! > 1) {
  await props.conversation.send({
    type: "text",
    payload: { text: `Welcome back! This is session #${props.conversation.session!.number}.` },
  })
}
```

### Nudge-only (no expiration)

Configure nudges without expiration. The conversation stays open indefinitely:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
lifecycle: {
  nudge: { after: "10m", interval: "30m", max: 2 },
}
```

### Expiration-only (no nudges)

Silently expire after inactivity without reminders:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
lifecycle: {
  expire: { after: "1h" },
}
```

### Different timeouts per channel

Each conversation file has its own lifecycle. Use this for channel-appropriate timing:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// conversations/support.ts - aggressive nudging, short timeout
lifecycle: {
  nudge: { after: "3m", interval: "5m", max: 3 },
  expire: { after: "15m" },
}

// conversations/sales.ts - patient, longer timeout
lifecycle: {
  nudge: { after: "30m", max: 1 },
  expire: { after: "24h" },
}
```

## Things to know

* **Timers are wall-clock based.** `after: "5m"` means 5 minutes of real time since the last user message, not "bot idle time."
* **Only user messages reset timers.** Bot messages, events, and workflow callbacks do not reset the nudge/expire timers.
* **Expiration always wins.** Even if nudges are suppressed during a workflow, the expire timer keeps ticking. Set `expire.after` longer than your longest expected workflow.
* **Session data survives expiration.** `session.number` persists. Only user state and transcript are cleared.
* **No behavior change without opt-in.** Conversations without `lifecycle` work exactly as before.
* **Lifecycle events are invisible to the LLM.** Nudge and expire events are not added to the transcript. Only your handler's `send()` calls appear in the conversation history.


# Send messages and content
Source: https://botpress.com/docs/adk/conversations/messages

Send text, images, cards, carousels, and more from your handler.

While `execute()` lets the AI model handle messaging automatically, sometimes you need to send messages directly from your handler. The `conversation.send()` method gives you full control over what gets sent.

## Sending a text message

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await conversation.send({
  type: "text",
  payload: { text: "Hello! How can I help you?" },
})
```

## Message types

The available message types depend on which channel your agent is deployed on. For [Webchat](/docs/webchat/get-started/introduction), the following types are supported:

| Type              | Payload                                     | Description                                                                                                                                                                                    |
| ----------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`            | `{ text, value? }`                          | Plain text message                                                                                                                                                                             |
| `markdown`        | `{ markdown }`                              | Markdown-formatted text                                                                                                                                                                        |
| `image`           | `{ imageUrl }`                              | Image from a URL                                                                                                                                                                               |
| `audio`           | `{ audioUrl }`                              | Audio file                                                                                                                                                                                     |
| `video`           | `{ videoUrl }`                              | Video file                                                                                                                                                                                     |
| `file`            | `{ fileUrl, title? }`                       | Downloadable file                                                                                                                                                                              |
| `location`        | `{ latitude, longitude, address?, title? }` | Map location                                                                                                                                                                                   |
| `card`            | `{ title, subtitle?, imageUrl?, actions }`  | Rich card with action buttons                                                                                                                                                                  |
| `carousel`        | `{ items }`                                 | Horizontal scrollable list of cards                                                                                                                                                            |
| `choice`          | `{ text, options, disableFreeText? }`       | Quick reply buttons                                                                                                                                                                            |
| `dropdown`        | `{ text, options, disableFreeText? }`       | Dropdown select menu                                                                                                                                                                           |
| `bloc`            | `{ items }`                                 | A group of mixed message types sent together                                                                                                                                                   |
| `custom`          | `{ url, name, data? }`                      | Raw custom message referencing a bundled component by URL                                                                                                                                      |
| `customComponent` | `{ component, props }`                      | Send a [custom component](/docs/adk/conversations/custom-components) directly. The runtime rewrites this into a `custom` message under the hood, so you get type-checked props instead of a raw URL |

Other channels (Slack, WhatsApp, Telegram) may support different message types. When you specify a channel on your conversation, TypeScript will only allow the message types that channel supports.

## Examples

### Card with actions

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await conversation.send({
  type: "card",
  payload: {
    title: "Order #1234",
    subtitle: "Shipped - arriving Thursday",
    imageUrl: "https://example.com/product.jpg",
    actions: [
      { action: "url", label: "Track shipment", value: "https://example.com/track/1234" },
      { action: "postback", label: "Contact support", value: "contact_support" },
    ],
  },
})
```

### Carousel

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await conversation.send({
  type: "carousel",
  payload: {
    items: [
      {
        title: "Basic Plan",
        subtitle: "$9/mo",
        imageUrl: "https://example.com/basic.png",
        actions: [{ action: "postback", label: "Select", value: "plan_basic" }],
      },
      {
        title: "Pro Plan",
        subtitle: "$29/mo",
        imageUrl: "https://example.com/pro.png",
        actions: [{ action: "postback", label: "Select", value: "plan_pro" }],
      },
    ],
  },
})
```

### Choice buttons

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await conversation.send({
  type: "choice",
  payload: {
    text: "How would you like to proceed?",
    options: [
      { label: "Check order status", value: "check_order" },
      { label: "Start a return", value: "start_return" },
      { label: "Talk to a human", value: "talk_to_human" },
    ],
  },
})
```

### Markdown

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await conversation.send({
  type: "markdown",
  payload: {
    markdown: "Here's a summary:\n\n- **Items**: 3\n- **Total**: $45.99\n- **Status**: Processing",
  },
})
```

## Typing indicators

The framework automatically starts a typing indicator when your handler begins and stops it when the handler finishes. You don't need to manage this yourself.

If you need manual control (e.g., you stopped typing to send a message and want to restart it before a slow operation), you can call the methods directly:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await conversation.startTyping()
await conversation.stopTyping()
```

## Conversation tags

Read and write metadata tags on the conversation:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const priority = conversation.tags.priority

conversation.tags.priority = "high"
conversation.tags.category = "billing"
```

<Note>
  Tags must be declared in `agent.config.ts` under `conversation.tags`. Check out our guide to [configuration your agent](/docs/adk/setup/configuration#tags) for more information.
</Note>

## Loading a conversation by ID

You can send messages to any conversation, not just the current one:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"

const otherConversation = await Conversation.get("conversation-id")
await otherConversation.send({
  type: "text",
  payload: { text: "Hello from another conversation!" },
})
```

This is useful for cross-conversation notifications or broadcasting messages.

## Combining with execute()

A common pattern is to send a direct message before or after handing control to the AI:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
handler: async ({ execute, conversation, type }) => {
  if (type === "message") {
    await conversation.send({
      type: "text",
      payload: { text: "Let me look into that for you." },
    })

    await execute({
      instructions: "You are a helpful assistant.",
    })
  }
}
```

Direct sends and AI-generated messages appear in the same conversation.


# Set up conversations
Source: https://botpress.com/docs/adk/conversations/setup

Handle user messages across channels.

Conversations are how your agent receives and responds to user messages. Each conversation file defines a handler that runs when a message arrives on a matching channel.

## Creating a conversation

Create a file in `src/conversations/` that exports a `Conversation`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"

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

This is the simplest possible conversation. It matches all channels and hands every message to the AI model with a system instruction.

You can test your conversation using the **Chat** page in the dev console. This requires the webchat integration, so install it first with `adk add webchat`.

<Frame>
  <img alt="Chat page in dev console" />

  <img alt="Chat page in dev console" />
</Frame>

## Channel matching

The `channel` field determines which integration channels this conversation handles:

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

  ```ts Specific channel highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  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={"theme":{"light":"light-plus","dark":"dark-plus"}} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  export default new Conversation({
    channel: [
      "chat.channel",
      "webchat.channel"
    ],
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```
</CodeGroup>

When you use `"*"`, the handler runs for any channel, but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// channel: "*" — message.payload is unknown
handler: async ({ message }) => {
  const text = message.payload.text // ❌ TypeScript error
}

// channel: "webchat.channel" — message.payload is fully typed
handler: async ({ message }) => {
  const text = message.payload.text // ✅ string
}
```

<Info>
  If multiple conversation files match the same channel, the most specific match wins. A conversation with `channel: "webchat.channel"` takes priority over one with `channel: "*"` for webchat messages.
</Info>

## Multiple conversations

You can create separate conversation files for different channels or use cases:

```
src/conversations/
├── webchat.ts        # Webchat messages
├── slack.ts          # Slack messages
└── support.ts        # Support channel
```

Each file exports a `Conversation` with its own channel, handler, and configuration. The ADK discovers them all automatically.

## Handler types

Your handler receives different types of requests. Check the `type` field to determine what you're handling:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Conversation({
  channel: "webchat.channel",
  handler: async (props) => {
    switch (props.type) {
      case "message":
        // A user sent a message
        await props.execute({ instructions: "You are a helpful assistant." })
        break

      case "event":
        // An integration event fired (e.g., conversationStarted)
        break

      case "workflow_request":
        // A workflow is asking the user for input
        break

      case "workflow_callback":
        // A workflow finished and is reporting back
        break

      case "workflow_notify":
        // A workflow is sending a progress update
        break

      case "nudge":
        // Lifecycle nudge (user has been idle)
        break

      case "expire":
        // Lifecycle expiration (session ending)
        break
    }
  },
})
```

Most conversations only need to handle `"message"`. The other types become relevant as you add [workflows](/docs/adk/workflows/create), [lifecycle management](/docs/adk/conversations/lifecycle), and [events](#listening-to-events).

## Handler parameters

Every handler type receives these common parameters:

| Parameter      | Type       | Description                                              |
| -------------- | ---------- | -------------------------------------------------------- |
| `type`         | `string`   | The request type (`"message"`, `"event"`, etc.)          |
| `conversation` | `object`   | Conversation instance for sending messages, reading tags |
| `state`        | `object`   | Mutable conversation state, auto-persisted               |
| `client`       | `object`   | Botpress client for API calls (tables, events, etc.)     |
| `execute`      | `function` | Run the AI model with instructions, tools, and knowledge |
| `chat`         | `Chat`     | Chat instance for transcript management                  |
| `channel`      | `string`   | The channel this request came from                       |

When `type` is `"message"`, you also get `message` with the message payload. When `type` is `"event"`, you get `event` with the event payload.

## Listening to events

By default, conversations only receive messages. To listen to integration events or custom events, add the `events` prop:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Conversation({
  channel: "webchat.channel",
  events: ["webchat:conversationStarted"],
  handler: async (props) => {
    if (props.type === "event" && props.event.type === "webchat:conversationStarted") {
      await props.conversation.send({
        type: "text",
        payload: { text: "Welcome! How can I help you?" },
      })
      return
    }

    await props.execute({ instructions: "You are a helpful assistant." })
  },
})
```

Events use the format `"integration:eventName"` for integration events, or just the event name for custom events defined in `agent.config.ts`.

## Conversation state

Each conversation can declare its own state schema, separate from the bot and user state in `agent.config.ts`:

```typescript highlight={3-6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Conversation({
  channel: "webchat.channel",
  state: z.object({
    topic: z.string().optional(),
    messageCount: z.number().default(0),
  }),
  handler: async ({ state, execute }) => {
    state.messageCount += 1

    await execute({
      instructions: `You are a helpful assistant. This is message #${state.messageCount}.`,
    })
  },
})
```

Conversation state is automatically persisted between handler calls.

<Tip>
  For more information about state scopes (conversation vs. bot vs. user), check out our guide on [managing states](/docs/adk/conversations/state).
</Tip>


# Manage state
Source: https://botpress.com/docs/adk/conversations/state

Store and reuse data across conversations, users, and the entire bot.

State lets your agent persist data between handler calls. The ADK provides three scopes depending on how long you need the data and who should have access to it.

## State scopes

| Scope            | Persists across                    | Defined in                | Accessed via                               |
| ---------------- | ---------------------------------- | ------------------------- | ------------------------------------------ |
| **Bot**          | All users and conversations        | `agent.config.ts`         | `import { bot } from "@botpress/runtime"`  |
| **User**         | All conversations for a given user | `agent.config.ts`         | `import { user } from "@botpress/runtime"` |
| **Conversation** | A single conversation              | Conversation `state` prop | Handler's `state` parameter                |

## Defining state schemas

### Bot and user state

Define bot and user state in `agent.config.ts`:

```typescript highlight={6-10, 12-18} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { z, defineConfig } from "@botpress/runtime"

export default defineConfig({
  name: "my-agent",

  bot: {
    state: z.object({
      ticketCounter: z.number().default(0),
    }),
  },

  user: {
    state: z.object({
      name: z.string().optional(),
      department: z.string().optional(),
      visitCount: z.number().default(0),
    }),
  },
})
```

Use `.default()` to set initial values and `.describe()` to document what each field is for.

### Conversation state

Define conversation state on a `Conversation` using the `state` prop:

```typescript highlight={5-8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation, z } from "@botpress/runtime"

export default new Conversation({
  channel: "webchat.channel",
  state: z.object({
    topic: z.string().optional(),
    messageCount: z.number().default(0),
  }),
  handler: async ({ state, execute }) => {
    state.messageCount += 1

    await execute({
      instructions: `You are a helpful assistant. Messages so far: ${state.messageCount}`,
    })
  },
})
```

## Reading and writing state

State objects are mutable and can be modified directly. Your changes are saved automatically—you don't need to call a save method.

## Bot state

You can access bot state anywhere in your agent (conversations, actions, tools, workflows):

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { bot } from "@botpress/runtime"

const counter = bot.state.ticketCounter
bot.state.ticketCounter = counter + 1
```

### User state

You can access user state anywhere the current user context exists:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { user } from "@botpress/runtime"

const name = user.state.name
user.state.visitCount = (user.state.visitCount || 0) + 1
```

### Conversation state

You can access conversation state via the `state` parameter in the conversation handler:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
handler: async ({ state, execute }) => {
  if (state.phase === "greeting") {
    state.phase = "main"
  }

  await execute({
    instructions: `Current phase: ${state.phase}`,
  })
}
```

## Loading by ID

You can load any user or conversation by ID to read and write their state and tags from anywhere in your agent:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { User, Conversation } from "@botpress/runtime"

const otherUser = await User.get("user-id")
console.log(otherUser.state.name)
otherUser.tags.role = "admin"

const otherConversation = await Conversation.get("conversation-id")
await otherConversation.send({
  type: "text",
  payload: { text: "Hello from another context!" },
})
```

Changes to loaded instances are auto-saved, just like the current user and conversation.

## State references

You can store workflow instances in state. They are saved automatically and loaded back as full instances when read:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation, Reference, z } from "@botpress/runtime"
import OnboardingWorkflow from "../workflows/onboarding"

export default new Conversation({
  channel: "webchat.channel",
  state: z.object({
    activeWorkflow: Reference.Workflow("onboarding").optional(),
  }),
  handler: async ({ state }) => {
    if (!state.activeWorkflow) {
      state.activeWorkflow = await OnboardingWorkflow.start({})
    }
  },
})
```

## Tags

Tags are string key-value pairs you can attach to bots, users, conversations, messages, and workflows. They're useful for categorization, filtering, and querying.

### Defining tags

Declare tags in `agent.config.ts`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default defineConfig({
  name: "my-agent",

  bot: {
    tags: {
      environment: { title: "Environment" },
    },
  },

  user: {
    tags: {
      role: { title: "Role" },
    },
  },

  conversation: {
    tags: {
      priority: { title: "Priority" },
    },
  },
})
```

### Reading and writing tags

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { bot, user } from "@botpress/runtime"

bot.tags.environment = "production"
user.tags.role = "admin"
```

You can access conversation tags via the `conversation` instance:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
handler: async ({ conversation }) => {
  conversation.tags.priority = "high"
  const priority = conversation.tags.priority
}
```

System tags set by integrations (keys containing `:`) are read-only:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const owner = conversation.tags["webchat:owner"]
```

## Bot and user identity

The `bot` and `user` objects also expose an `id` property:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { bot, user } from "@botpress/runtime"

const botId = bot.id
const userId = user.id
```


# Define tools
Source: https://botpress.com/docs/adk/conversations/tools

Give the AI model functions it can call during execution.

Tools are functions the AI model can call during `execute()`. The model reads the tool's name, description, and input schema to decide when and how to call it. You define the logic; the model decides when to use it.

## Creating a tool

Create a file anywhere under `src/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous, z } from "@botpress/runtime"

export default new Autonomous.Tool({
  name: "getWeather",
  description: "Get the current weather for a city",
  input: z.object({
    city: z.string().describe("The city name"),
    unit: z.enum(["celsius", "fahrenheit"]).optional().describe("Temperature unit"),
  }),
  output: z.object({
    temperature: z.number(),
    condition: z.string(),
  }),
  handler: async ({ city, unit }) => {
    const weather = await fetchWeatherData(city, unit)
    return {
      temperature: weather.temp,
      condition: weather.condition,
    }
  },
})
```

The `input` and `output` schemas use Zod. Use `.describe()` on each field so the model knows what to pass. The handler receives validated input and returns typed output.

## Using tools in a conversation

Pass tools to `execute()` via the `tools` array:

```typescript highlight={10} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import getWeather from "../tools/weather"
import createTicket from "../tools/ticket"

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

The model decides which tools to call based on the conversation. It can call multiple tools across multiple iterations before responding.

## Inline tools

You can define tools directly inside a handler without creating a separate file:

```typescript highlight={6-15, 19} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous, z, Conversation } from "@botpress/runtime"

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    const lookupOrder = new Autonomous.Tool({
      name: "lookupOrder",
      description: "Look up an order by ID",
      input: z.object({ orderId: z.string() }),
      output: z.object({ status: z.string(), total: z.number() }),
      handler: async ({ orderId }) => {
        const order = await db.findOrder(orderId)
        return { status: order.status, total: order.total }
      },
    })

    await execute({
      instructions: "You are an order support agent.",
      tools: [lookupOrder],
    })
  },
})
```

This is useful for tools that are only relevant to a single type of conversation.

## Writing good descriptions

The `description` field is how the model decides when to use your tool. Be specific about what the tool does and when to use it:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Too vague
description: "Gets data"

// Clear and specific
description: "Look up a customer's order by order ID. Use this when the user asks about an order status, shipment tracking, or order details."
```

Use `.describe()` on input fields for the same reason:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
input: z.object({
  query: z.string().describe("The search query, e.g. 'wireless headphones under $50'"),
  maxResults: z.number().optional().describe("Maximum results to return, defaults to 10"),
})
```

## Signals

Tools can throw signals to influence the AI loop without returning a normal result.

### ThinkSignal

A `ThinkSignal` throws context back into the model's reasoning without producing a tool output. This is useful when a tool finds no results and you want the model to try a different approach:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous } from "@botpress/runtime"

handler: async ({ query }) => {
  const results = await search(query)

  if (results.length === 0) {
    throw new Autonomous.ThinkSignal(
      "No results found",
      "No results matched the query. Try rephrasing or broadening the search."
    )
  }

  return results
}
```

## Actions as tools

Actions are reusable functions that can be called from anywhere in your agent—conversations, workflows, other actions, or external API clients. Tools only work inside `execute()`, where the AI model decides when to call them based on the conversation.

You can convert any action into a tool by calling its `asTool()` method and passing it into `tools`:

```typescript highlight={8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation, actions } from "@botpress/runtime"

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

<Tip>
  Check out our guide on [building actions](/docs/adk/external/actions) for more information.
</Tip>

## Workflows as tools

Workflows are long-running background processes that can span multiple steps and run independently of the conversation. Converting a workflow to a tool lets the model kick one off:

```typescript highlight={9} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import orderWorkflow from "../workflows/order"

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are an order management assistant.",
      tools: [orderWorkflow.asTool()],
    })
  },
})
```

<Tip>
  Check out our guide on [creating workflows](/docs/adk/workflows/create) for more information.
</Tip>

## Calling actions from tools

Tools can call actions for reusable logic:

```typescript highlight={8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous, actions, z } from "@botpress/runtime"

export default new Autonomous.Tool({
  name: "processRefund",
  description: "Process a refund for an order",
  input: z.object({ orderId: z.string() }),
  handler: async ({ orderId }) => {
    const result = await actions.processRefund({ orderId })
    return result
  },
})
```


# Knowledge bases
Source: https://botpress.com/docs/adk/data/knowledge

Give your agent access to documents, websites, and files.

Knowledge bases give your agent searchable access to documents, websites, and files. Pass one to `execute()` and the model searches it automatically when prompted, returning any results it finds with citations.

## Create a knowledge base

Create a file in `src/knowledge/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Knowledge, DataSource } from "@botpress/runtime"

export default new Knowledge({
  name: "product-docs",
  description: "Product documentation and FAQ",
  sources: [
    DataSource.Website.fromSitemap("https://docs.example.com/sitemap.xml"),
  ],
})
```

When multiple KBs are passed to `execute()`, the LLM reads each one's `description` to pick which to search. Keep descriptions short and specific.

Browse your knowledge bases, inspect indexing status, and view individual files from the dev console:

<Frame>
  <img alt="Knowledge page in dev console" />

  <img alt="Knowledge page in dev console" />
</Frame>

## Use it in a conversation

Pass knowledge bases to `execute()` via the `knowledge` array. The model searches them automatically when it needs information, and includes citations back to the source documents:

```typescript highlight={10} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import ProductDocs from "../knowledge/product-docs"
import FAQ from "../knowledge/faq"

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    await execute({
      instructions: "Answer questions using the documentation. Cite your sources.",
      knowledge: [ProductDocs, FAQ],
    })
  },
})
```

## Data sources

A knowledge base indexes one or more data sources. The ADK ships two types: websites and local directories.

### Website from sitemap

Index all pages in a sitemap:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const DocsSource = DataSource.Website.fromSitemap(
  "https://example.com/sitemap.xml",
  {
    filter: ({ url }) => !url.includes("/admin"),
    maxPages: 1000,
    maxDepth: 10,
  }
)
```

### Website from base URL

Crawl a website starting from a URL:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const DocsSource = DataSource.Website.fromWebsite(
  "https://example.com",
  {
    filter: ({ url }) => !url.includes("/admin"),
    maxPages: 500,
    maxDepth: 5,
  }
)
```

For JS-rendered sites, add `fetch: "integration:browser"` to the options and add the Browser integration to your agent (see [Integrations](/docs/adk/setup/integrations)).

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const DocsSource = DataSource.Website.fromWebsite("https://example.com", {
  fetch: "integration:browser",
})
```

### Website from llms.txt

Index pages referenced in an `llms.txt` file:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const DocsSource = DataSource.Website.fromLlmsTxt(
  "https://example.com/llms.txt"
)
```

### Website from specific URLs

Index a fixed list of pages:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const DocsSource = DataSource.Website.fromUrls([
  "https://example.com/pricing",
  "https://example.com/faq",
  "https://example.com/terms",
])
```

### Website source options

All four website factories accept the same options:

| Option     | Type                 | Description                                                                                                                    |
| ---------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`       | `string`             | Optional unique identifier for the source                                                                                      |
| `filter`   | `(ctx) => boolean`   | Filter function receiving `{ url, lastmod?, changefreq?, priority? }`                                                          |
| `fetch`    | `string \| function` | Fetch strategy: `"node:fetch"` (default) for static sites, `"integration:browser"` for JS-rendered sites, or a custom function |
| `maxPages` | `number`             | Maximum pages to index (1–50000, default: 50000)                                                                               |
| `maxDepth` | `number`             | Maximum sitemap depth (1–20, default: 20)                                                                                      |

### Directory

Index files from a local directory:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const FileSource = DataSource.Directory.fromPath("./src/knowledge/docs", {
  filter: (filePath) => filePath.endsWith(".md") || filePath.endsWith(".txt"),
})
```

| Option   | Type                            | Description                               |
| -------- | ------------------------------- | ----------------------------------------- |
| `id`     | `string`                        | Optional unique identifier for the source |
| `filter` | `(filePath: string) => boolean` | Decide which files to include by path     |

## Search a knowledge base directly

To search a KB outside of `execute()`, call `search()` on the instance. This is useful for custom retrieval, suggested-articles user interfaces, or populating context manually:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const result = await ProductDocs.search("how do I reset my password?", {
  limit: 5,
})

for (const passage of result.passages) {
  console.log(passage.content, passage.metadata)
}
```

## Re-index a knowledge base

By default, knowledge bases index during `adk dev` and `adk deploy`.

### On a schedule

To re-index on a schedule, use a [workflow](/docs/adk/workflows/create):

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow } from "@botpress/runtime"
import ProductDocs from "../knowledge/product-docs"

export default new Workflow({
  name: "refreshKnowledge",
  schedule: "0 0 * * *",
  handler: async () => {
    await ProductDocs.refresh()
  },
})
```

### Force re-indexing

To force re-indexing even if content hasn't changed pass in `force: true`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await ProductDocs.refresh({ force: true })
```

### Re-index a single source

To re-index a single source within a knowledge base, pass in the source ID:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await ProductDocs.refreshSource("my-source-id", { force: true })
```


# Tables
Source: https://botpress.com/docs/adk/data/tables

Define and query structured data storage.

Tables provide typed, structured storage for your agent. You define a schema using `z` from `@botpress/runtime`, and the ADK syncs it with Botpress on deploy. Tables are accessible from conversations, workflows, actions, tools, and triggers.

## Creating a table

Create a file in `src/tables/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Table, z } from "@botpress/runtime"

export default new Table({
  name: "OrderTable",
  description: "Customer orders",
  keyColumn: "userId",
  columns: {
    userId: z.string(),
    items: z.array(z.string()),
    total: z.number(),
    status: z.string(),
  },
})
```

The `description` field is optional but useful when the table gets surfaced to the LLM (via Zai or knowledge). `keyColumn` is optional too; it sets the default key used when calling [`.upsertRows()`](#upsert-rows) so you don't have to pass it on every call.

<Frame>
  <img alt="Tables page in dev console" />

  <img alt="Tables page in dev console" />
</Frame>

### Naming rules

Table names:

* Must start with a letter, underscore, or `$`
* Must be 35 characters or less
* Must contain only letters, numbers, and underscores
* Must end with `Table`
* Cannot be a UUID

### Searchable columns

You can mark columns as searchable to enable semantic search:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Table({
  name: "TicketTable",
  columns: {
    title: { schema: z.string(), searchable: true },
    description: { schema: z.string(), searchable: true },
    status: z.string(),
    priority: z.string(),
  },
})
```

### Computed columns

A computed column is derived from other columns. Set `computed: true`, pass the columns it depends on into `dependencies`, and return its value from `value`:

```typescript highlight={7,9-10} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Table({
  name: "OrderTable",
  columns: {
    quantity: z.number(),
    unitPrice: z.number(),
    total: {
      computed: true,
      schema: z.number(),
      dependencies: ["quantity", "unitPrice"],
      value: (row) => row.quantity * row.unitPrice,
    },
  },
})
```

Computed columns recalculate whenever their dependencies change. When you write to the table, you can pass `waitComputed: true` to block any further modifications to the table until the recalculation finishes:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await OrderTable.createRows({
  rows: [{ quantity: 3, unitPrice: 20 }],
  waitComputed: true,
})
```

## Managing table data

You can manage your table data in the dev console under **Data > Tables**. Here, you can:

* View the sync state between your code and Botpress' servers
* Add/update/delete rows
* Filter and sort
* Export to CSV
* Copy data between development and production environments

## CRUD operations

To perform operations on your table within your agent's code, import the table and use the typed instance methods.

### Create rows

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OrderTable from "../tables/order-table"

const { rows } = await OrderTable.createRows({
  rows: [{ userId: "user123", total: 99.99, status: "pending" }],
})
```

### Find rows

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await OrderTable.findRows({
  filter: { status: "pending" },
  orderBy: "createdAt",
  orderDirection: "desc",
  limit: 10,
})
```

### Get a single row

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const row = await OrderTable.getRow({ id: 42 })
```

### Update rows

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await OrderTable.updateRows({
  rows: [{ id: orders[0].id, status: "completed" }],
})
```

### Upsert rows

Insert or update based on a key column:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { inserted, updated } = await OrderTable.upsertRows({
  keyColumn: "userId",
  rows: [{ userId: "user123", total: 149.99, status: "pending" }],
})
```

If you [set `keyColumn` on the table](#creating-a-table), you can omit it here.

<Note>
  If `keyColumn` is omitted on both the table defintion and the `upsertRows` call, it defaults to `id`.
</Note>

### Delete rows

<CodeGroup>
  ```typescript Delete rows by name theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  await OrderTable.deleteRows({ status: "cancelled" })
  ```

  ```typescript Delete rows by ID theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  await OrderTable.deleteRowIds([1, 2, 3])
  ```

  ```typescript Delete all rows theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  await OrderTable.deleteAllRows()
  ```
</CodeGroup>

## Filtering

When calling `findRows()`, you can pass in filters for specific rows. These can use [MongoDB-style operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/) for advanced queries:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await OrderTable.findRows({
  filter: {
    total: { $gt: 100 },
    status: { $in: ["pending", "processing"] },
  },
})
```

### Operators

| Operator   | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| `$eq`      | Equal to                                                          |
| `$ne`      | Not equal to                                                      |
| `$gt`      | Greater than                                                      |
| `$gte`     | Greater than or equal                                             |
| `$lt`      | Less than                                                         |
| `$lte`     | Less than or equal                                                |
| `$in`      | In array                                                          |
| `$nin`     | Not in array                                                      |
| `$exists`  | Field exists                                                      |
| `$regex`   | Regex match                                                       |
| `$options` | Regex flags: `"i"` for case-insensitive, `"c"` for case-sensitive |

### Logical operators

You can combine filters with `$and`, `$or`, and `$not`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await OrderTable.findRows({
  filter: {
    $or: [
      { status: "pending" },
      { total: { $gt: 500 } },
    ],
  },
})
```

## Semantic search

You can search across [`searchable` columns](#searchable-columns) using natural language:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await TicketTable.findRows({
  search: "VPN connection issues",
  limit: 10,
})
```

Combine with filters for hybrid queries:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await TicketTable.findRows({
  search: "network problems",
  filter: { status: "open" },
  limit: 20,
})
```

## Aggregation

Aggregation groups rows by one or more columns and computes summary statistics for other columns. This transforms your table data into summary reports.

Pass a `group` object to `findRows()` where each key is a column name and the value is either a single operation or an array of operations:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await OrderTable.findRows({
  group: {
    status: "key",              // Group by status
    total: ["sum", "avg"],      // Sum and average the total column
    id: "count",                // Count rows in each group
  },
})
```

The returned rows have different fields based on your group configuration. The field names combine the column name (in `camelCase`) with the operation:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// For the group config above, each row in the result contains:
{
  statusKey: "pending",     // The grouping value
  totalSum: 1500.00,        // Sum of totals in this group
  totalAvg: 125.00,         // Average of totals in this group
  idCount: 12,              // Number of rows in this group
}
```

Operations vary by column type:

| Operation | Available for           | Returns        | Description                 |
| --------- | ----------------------- | -------------- | --------------------------- |
| `key`     | All types               | Same as column | Groups rows by this value   |
| `count`   | All types               | `number`       | Number of rows in the group |
| `sum`     | Numbers                 | `number`       | Sum of values               |
| `avg`     | Numbers                 | `number`       | Average of values           |
| `max`     | Numbers, strings, dates | Same as column | Maximum value               |
| `min`     | Numbers, strings, dates | Same as column | Minimum value               |
| `unique`  | All types               | Array          | Array of unique values      |


# Create actions
Source: https://botpress.com/docs/adk/external/actions

Create reusable functions that can be called from anywhere in your agent or from external systems.

Actions are reusable functions that hold shared business logic. You can call them from your agent's code (via [conversations](#from-a-conversation), [workflows](#from-a-workflow), [triggers](#from-a-trigger), [tools](#from-a-tool), or  other actions). You can also [call them over HTTP](#calling-from-external-systems) from external systems.

## Creating an action

Create a file in `src/actions/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Action, z } from "@botpress/runtime"

export default new Action({
  name: "calculateTotal",
  description: "Calculate the total price including tax",
  input: z.object({
    items: z.array(z.object({
      price: z.number(),
      quantity: z.number(),
    })),
    taxRate: z.number().default(0.08),
  }),
  output: z.object({
    subtotal: z.number(),
    tax: z.number(),
    total: z.number(),
  }),
  handler: async ({ input }) => {
    const subtotal = input.items.reduce(
      (sum, item) => sum + item.price * item.quantity, 0
    )
    const tax = subtotal * input.taxRate
    return { subtotal, tax, total: subtotal + tax }
  },
})
```

Action names must be alphanumeric with no underscores, dashes, or spaces (e.g. `calculateTotal`, not `calculate_total`).

Browse and test actions from the dev console:

<Frame>
  <img alt="Actions page in dev console" />

  <img alt="Actions page in dev console" />
</Frame>

### Caching results

Set `cached: true` to cache an action's output by its input. Subsequent calls with the same input return the cached result instead of re-running the handler:

```typescript highlight={3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Action({
  name: "fetchExchangeRate",
  cached: true,
  input: z.object({ from: z.string(), to: z.string() }),
  output: z.object({ rate: z.number() }),
  handler: async ({ input }) => {
    const rate = await fetchRate(input.from, input.to)
    return { rate }
  },
})
```

This is useful for actions that are pure, perform an expensive calculation, and are called repeatedly with the same inputs.

## Calling actions

Import `actions` from `@botpress/runtime` and call any action by name. The action's input and output are fully typed.

### From a conversation

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation, actions } from "@botpress/runtime"

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    const result = await actions.calculateTotal({
      items: [{ price: 10, quantity: 2 }],
    })
    console.log(result.total)

    await execute({ instructions: "You are a helpful assistant." })
  },
})
```

### From a workflow

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow, actions } from "@botpress/runtime"

export default new Workflow({
  name: "processOrder",
  handler: async ({ input, step }) => {
    const totals = await step("calculate", async () => {
      return await actions.calculateTotal({ items: input.items })
    })
  },
})
```

### From a tool

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Autonomous, actions, z } from "@botpress/runtime"

export default new Autonomous.Tool({
  name: "getOrderTotal",
  description: "Calculate the total for an order",
  input: z.object({ items: z.array(z.object({ price: z.number(), quantity: z.number() })) }),
  output: z.object({ total: z.number() }),
  handler: async ({ items }) => {
    const result = await actions.calculateTotal({ items })
    return { total: result.total }
  },
})
```

### From a trigger

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Trigger, actions } from "@botpress/runtime"

export default new Trigger({
  name: "onOrderCreated",
  events: ["orderPlaced"],
  handler: async ({ event }) => {
    await actions.calculateTotal({ items: event.payload.items })
  },
})
```

## As a tool

While actions are just functions that can be called from anywhere, [tools](/docs/adk/conversations/tools) only exist inside `execute()` and are called by the LLM. If you want the LLM to have access to a certain action:

1. Convert it to a tool with `.asTool()`
2. Pass it into the `tools` field:

```typescript highlight={8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation, actions } from "@botpress/runtime"

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a shopping assistant.",
      tools: [actions.calculateTotal.asTool()],
    })
  },
})
```

You should always provide a detailed description that helps the LLM decide when to use a tool. When converting an action to a tool, you can override its description by passing a string into the`description` field:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
actions.calculateTotal.asTool({ description: "Calculate the total price with tax for the user's cart" })
```

## Integration actions

When you add an integration, its actions are available under `actions.<integration>`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { actions } from "@botpress/runtime"

await actions.webchat.showWebchat({ conversationId })
await actions.slack.addReaction({ name: "thumbsup", channel, timestamp })
```

## Calling from external systems

Actions are exposed via the Botpress [Runtime API](/docs/api-reference/runtime-api/getting-started)'s [`callAction`](/docs/api-reference/runtime-api/openapi/callAction) endpoint. External services can call your agent's actions over HTTP:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST https://api.botpress.cloud/v1/chat/actions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "x-bot-id: YOUR_BOT_ID" \
  -d '{
    "type": "calculateTotal",
    "input": {
      "items": [{ "price": 10, "quantity": 2 }],
      "taxRate": 0.08
    }
  }'
```

This makes actions the bridge between your agent and external systems. A backend service, a webhook handler, or another application can trigger your agent's logic without going through a conversation.


# Set up triggers
Source: https://botpress.com/docs/adk/external/triggers

React to events from integrations and custom events.

Triggers subscribe to events and run a handler when those events fire. Unlike conversations (which respond to user messages), triggers respond to system events, integration events, and custom events you define.

## Creating a trigger

Create a file in `src/triggers/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Trigger } from "@botpress/runtime"

export default new Trigger({
  name: "onConversationStarted",
  events: ["webchat:conversationStarted"],
  handler: async ({ event }) => {
    console.log("New conversation started:", event.payload)
  },
})
```

The `events` array lists which events this trigger subscribes to. The handler runs when any of the listed events fire.

<Note>
  Trigger names must be at least 3 characters and contain only alphanumeric characters and underscores.
</Note>

## Viewing triggers in the dev console

You can browse your triggers from the dev console at **Components > Triggers**:

<Frame>
  <img alt="Triggers page in dev console" />

  <img alt="Triggers page in dev console" />
</Frame>

## Event format

Events use the format `"integration:eventName"` for integration events, or just the event name for custom events defined in `agent.config.ts`.

The handler receives a single `event` parameter:

| Parameter       | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `event.type`    | `string` | The event type that fired |
| `event.payload` | `object` | Event-specific data       |

To make API calls from a trigger, pull the client from the runtime context: `const client = context.get("client")`.

## Multiple events

A trigger can subscribe to multiple events and handle each differently:

```typescript highlight={4-8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Trigger({
  name: "onLinearIssue",
  description: "Handle Linear issue events",
  events: [
    "linear:issueCreated",
    "linear:issueUpdated",
    "linear:issueDeleted",
  ],
  handler: async ({ event }) => {
    if (event.type === "linear:issueCreated") {
      // Handle new issue
    } else if (event.type === "linear:issueUpdated") {
      // Handle update
    } else if (event.type === "linear:issueDeleted") {
      // Handle deletion
    }
  },
})
```

## Custom events

Triggers can subscribe to custom events you define in `agent.config.ts`:

```typescript title="agent.config.ts" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default defineConfig({
  events: {
    orderPlaced: {
      description: "Fired when an order is placed",
      schema: z.object({
        orderId: z.string(),
        total: z.number(),
      }),
    },
  },
})
```

```typescript title="src/triggers/on-order.ts" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Trigger } from "@botpress/runtime"

export default new Trigger({
  name: "onOrderPlaced",
  events: ["orderPlaced"],
  handler: async ({ event }) => {
    const { orderId, total } = event.payload
    // Process the order
  },
})
```

## Using actions from triggers

Triggers can call actions for reusable logic:

```typescript highlight={8-10} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Trigger, actions } from "@botpress/runtime"

export default new Trigger({
  name: "onConversationStarted",
  events: ["webchat:conversationStarted"],
  handler: async ({ event }) => {
    if (event.payload.conversationId) {
      await actions.webchat.showWebchat({
        conversationId: event.payload.conversationId,
      })
    }
  },
})
```


# Introduction to the ADK
Source: https://botpress.com/docs/adk/introduction

TypeScript framework for building AI agents on Botpress.

The Agent Development Kit (ADK) is a **CLI tool and development framework for building AI agents on Botpress**. It provides a streamlined development experience with TypeScript support, hot reloading, and type-safe APIs for creating AI applications.

You write conversations, workflows, tools, and actions as code. Botpress handles hosting, scaling, and channel delivery.

<Frame>
  <img alt="Botpress ADK" />

  <img alt="Botpress ADK" />
</Frame>

## What you can build

* **Customer support agents** that resolve tickets, look up orders, and escalate to humans
* **Internal tools** that automate workflows across Slack, email, and databases
* **Sales assistants** that qualify leads, book meetings, and sync with your CRM
* **Multi-channel bots** that work across webchat, WhatsApp, Telegram, and more

## How it works

You write TypeScript. The ADK CLI handles the rest.

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk init my-agent     # Scaffold a project
adk dev               # Run locally with hot reload
adk deploy            # Ship to Botpress Cloud
```

Your agent is organized around a few core primitives:

| Primitive             | What it does                            |
| --------------------- | --------------------------------------- |
| **Conversations**     | Handle user messages on a channel       |
| **Workflows**         | Run multi-step background processes     |
| **Tools**             | Give the AI model functions it can call |
| **Actions**           | Reusable logic callable from anywhere   |
| **Tables**            | Structured data storage                 |
| **Knowledge**         | RAG-powered document retrieval          |
| **Triggers**          | React to external events                |
| **Custom components** | Render custom React UI in webchat       |
| **Evals**             | Automated conversation tests            |

Each primitive lives in its own file. The ADK discovers them automatically, no manual registration.

## Start here

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/adk/quickstart">
    Install the ADK and deploy your first agent in minutes.
  </Card>

  <Card title="What's new" icon="newspaper" href="/changelog">
    Latest features, improvements, and breaking changes.
  </Card>
</CardGroup>


# Quickstart
Source: https://botpress.com/docs/adk/quickstart

Install the ADK and create your first agent project.

By the end of this guide, you'll have a working AI agent that responds to messages on Webchat. It takes about 5 minutes.

<Info>
  You will need:

  * A [Botpress account](https://sso.botpress.cloud)
  * [Node.js](https://nodejs.org/en) (v22.0.0 or higher)
  * A supported package manager — [bun](https://bun.sh), [pnpm](https://pnpm.io), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com)
</Info>

<Tip>
  Visual learner?

  Check out our [ADK Setup Guide with Claude Code and Cursor](https://youtu.be/ZsprRQhTtfo) on YouTube for a step-by-step video guide.
</Tip>

## Installation

Install the ADK CLI globally:

<CodeGroup>
  ```bash macOS & Linux theme={"theme":{"light":"light-plus","dark":"dark-plus"}} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
  ```

  ```powershell Windows (PowerShell) theme={"theme":{"light":"light-plus","dark":"dark-plus"}} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
  ```
</CodeGroup>

Then, verify the installation:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk --version
```

Log in to your Botpress account:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk login
```

This will open a browser window for authentication. Once complete, the CLI stores your credentials locally.

## Create your agent

Initialize a new agent project:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk init my-agent
```

The wizard walks you through three steps:

1. **Select a template**: Pick `hello-world`. This creates a simple agent that responds to webchat messages using an AI model.
2. **Select a package manager**: We recommend [bun](https://bun.sh) for the fastest experience. npm, pnpm, and yarn also work. If you only have one installed, this step is skipped.
3. **Link to Botpress**: Select the workspace you want to deploy to. The CLI creates a bot in that workspace and connects your project to it.

The CLI then automatically installs dependencies and sets up your project in the `my-agent` directory.

Navigate into your project:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cd my-agent
```

## Test your agent

Now, you’re ready to test your agent.

### Start the development server

Start the development server with hot reloading:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk dev
```

This builds your agent, deploys it to a development bot on Botpress, and starts the dev console at [`http://localhost:3001/`](http://localhost:3001/). Press <kbd>space</kbd> in the terminal to open it in your browser.

### View in the dev console

The dev console is your local control panel for building and debugging. Within the dev console, you can:

* Chat with your agent
* Browse its components (actions, workflows, triggers)
* Manage data (tables, knowledge bases, files)
* Run evals
* Inspect traces and logs
* Configure integrations

Go to the **Chat** page and send a message to test your agent:

<Frame>
  <img alt="ADK dev console" />

  <img alt="ADK dev console" />
</Frame>

The dev server watches your files and rebuilds on every change.

### Chat in the terminal

Alternatively, open a new terminal window and start a conversation with your agent from the command line:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk chat
```

```txt theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Botpress Chat
Type "exit" or press ESC key to quit
👤 Hey!
🤖 Hello! How can I assist you today?
>>
```

## Deploy your agent

When you're ready to go live:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk deploy
```

This builds your agent for production, runs preflight checks (integration changes, config diffs), syncs your knowledge bases and tables, and uploads everything to Botpress. The CLI walks you through any changes that need approval before deploying.

Once deployed, your agent is live in the workspace you linked during `adk init`.

<Check>
  You deployed your first agent using the ADK!
</Check>

***

Next, learn what's in the project you just created and how to configure it:

<Card title="Agent configuration" icon="settings" href="/adk/setup/configuration">
  Project structure, models, state, and dependencies.
</Card>


# Configuration
Source: https://botpress.com/docs/adk/setup/configuration

Understand your project structure and how to configure your agent.

## Project structure

Here's a breakdown of the key files in your project after running `adk init`:

<Tree>
  <Tree.Folder name="src">
    <Tree.Folder name="actions">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="conversations">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="knowledge">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="tables">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="triggers">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="workflows">
      <Tree.File name="index.ts" />
    </Tree.Folder>
  </Tree.Folder>

  <Tree.Folder name="evals">
    <Tree.File name="index.ts" />
  </Tree.Folder>

  <Tree.File name=".mcp.json" />

  <Tree.File name="agent.config.ts" />

  <Tree.File name="agent.json" />

  <Tree.File name="agent.local.json" />

  <Tree.File name="AGENTS.md" />

  <Tree.File name="CLAUDE.md" />
</Tree>

The ADK scans `src/` and discovers primitives automatically. Each file exports a primitive (a `Conversation`, `Workflow`, `Action`, etc.) and the framework registers it at build time.

## `agent.config.ts`

Everything about your agent is configured in `agent.config.ts` by calling `defineConfig` and passing in a configuration object.

Here's the `hello-world` template default configuration with all available fields shown:

```typescript expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { z, defineConfig } from "@botpress/runtime"

export default defineConfig({
  // Identity
  name: "my-agent",
  description: "An AI agent built with Botpress ADK",

  // LLM models
  defaultModels: {
    autonomous: "cerebras:gpt-oss-120b",
    zai: "cerebras:gpt-oss-120b",
  },

  // Persistent state
  bot: {
    state: z.object({}),
    tags: {},
  },
  user: {
    state: z.object({}),
    tags: {},
  },

  // Metadata tags
  conversation: { tags: {} },
  message: { tags: {} },
  workflow: { tags: {} },

  // Sensitive values (API keys, tokens)
  secrets: {},

  // Deploy-time settings
  configuration: {
    schema: z.object({}),
  },

  // Integrations
  dependencies: {
    integrations: {},
  },

  // Custom events
  events: {},

  // Test settings
  evals: {},
})
```

### Models

The `defaultModels` field controls which LLM your agent uses:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
defaultModels: {
  autonomous: "cerebras:gpt-oss-120b",
  zai: "cerebras:gpt-oss-120b",
},
```

| Model        | Used by                                                          |
| ------------ | ---------------------------------------------------------------- |
| `autonomous` | `execute()` calls in conversations and workflows                 |
| `zai`        | Zai operations like `zai.extract()`, `zai.check()`, `zai.text()` |

If you don't set `defaultModels`, the ADK defaults to `openai:gpt-4.1-mini-2025-04-14` for autonomous and `openai:gpt-4.1-2025-04-14` for zai.

You can pass an array of models for fallback. If the first model fails, the next one is tried:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
defaultModels: {
  autonomous: ["cerebras:gpt-oss-120b", "openai:gpt-4.1-2025-04-14"],
},
```

You can also browse and set models from the dev console under **Settings > LLM Config**.

To override the model on a specific `execute()` call:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await execute({
  model: "openai:gpt-4.1-2025-04-14",
  instructions: "You are a helpful assistant.",
})
```

### State

The `state` field lets you define schemas for data that your agent can persist across a certain scope. There are two available scopes:

| Scope  | Persists across                    | Use for                        |
| ------ | ---------------------------------- | ------------------------------ |
| `bot`  | All conversations and users        | Global counters, shared config |
| `user` | All conversations for a given user | Preferences, profile data      |

You can define schemas for state using Zod. The ADK generates TypeScript types from them, so state access is fully typed:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bot: {
  state: z.object({
    totalConversations: z.number().default(0),
  }),
},
user: {
  state: z.object({
    name: z.string().optional(),
    preferredLanguage: z.string().default("en"),
  }),
},
```

<Tip>
  For more information about reading and writing state at runtime, check out our guide to [managing states](/docs/adk/conversations/state).
</Tip>

### Tags

The `tags` field lets you define metadata that you can attach to bots, users, conversations, messages, and workflows:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bot: {
  tags: {
    environment: { title: "Environment", description: "dev or prod" },
  },
},
conversation: {
  tags: {
    priority: { title: "Priority" },
  },
},
```

Tags are useful for filtering and organizing data in the Botpress platform.

### Secrets

The `secrets` field lets you store sensitive values, like API keys or tokens. They are declared here, but values are managed separately per environment and never committed to version control:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
secrets: {
  OPENAI_KEY: { description: "OpenAI API key" },
  SENTRY_DSN: { optional: true, description: "Error tracking DSN" },
},
```

<Tip>
  For more information about using secrets, check out our guide on [setting up your environment](/docs/adk/setup/environment#secrets).
</Tip>

### Configuration

The `configuration` field defines static, deploy-time settings. Unlike state, these are read-only at runtime:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
configuration: {
  schema: z.object({
    apiEndpoint: z.string().default("https://api.example.com"),
    enableBeta: z.boolean().default(false),
  }),
},
```

<Tip>
  For managing configuration values across environments, check out our guide to [setting up your environment](/docs/adk/setup/environment#configuration).
</Tip>

### Dependencies

Dependencies declare which integrations your agent uses. Add them with the CLI:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk add webchat
adk add slack@latest
```

The CLI resolves the version and updates `agent.config.ts`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
dependencies: {
  integrations: {
    webchat: "webchat@0.3.0",
    slack: "slack@1.0.0",
  },
},
```

<Tip>
  For more information about finding, configuring, and managing integrations, check out our [integrations guide](/docs/adk/setup/integrations).
</Tip>

### Custom events

The `events` field lets you define custom events your agent can emit and subscribe to:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
events: {
  orderPlaced: {
    description: "Fired when an order is placed",
    schema: z.object({
      orderId: z.string(),
      total: z.number(),
    }),
  },
},
```

You can then listen for these events within triggers and conversations. For more information, check out our guide on [setting up triggers](/docs/adk/external/triggers).

### Evals

The `evals` field lets you configure how your agent's automated tests run:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
evals: {
  idleTimeout: 15000,
  judgePassThreshold: 3,
  judgeModel: "openai:gpt-4o",
},
```

| Field                | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `idleTimeout`        | Milliseconds to wait for the agent to respond before timing out |
| `judgePassThreshold` | Pass threshold for LLM judge assertions (1-5)                   |
| `judgeModel`         | Model used for LLM judge assertions                             |

<Tip>
  For more information, check out our full guide to [writing and running evals](/docs/adk/testing/evals).
</Tip>


# Environment setup
Source: https://botpress.com/docs/adk/setup/environment

Manage secrets, configuration values, and development/production environments.

The ADK separates development and production into two environments. Secrets and configuration values are stored per environment, so your dev API keys never touch production.

You can switch between environments in the dev console using the environment toggle in the upper-right corner. This controls which environment's secrets, configuration, and data you view/edit.

<Tip>
  You can also toggle between environments with <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Mac) or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Windows/Linux).
</Tip>

<Frame>
  <img alt="Environment selector in dev console" />

  <img alt="Environment selector in dev console" />
</Frame>

## Project files

Your project has three files that manage environment state:

| File                | Contains                                 | Committed to version control |
| ------------------- | ---------------------------------------- | ---------------------------- |
| `agent.json`        | Production bot ID, workspace ID, API URL | Yes                          |
| `agent.local.json`  | Development bot ID                       | No (gitignored)              |
| `.adk/secrets.json` | Secret values for dev and prod           | No (gitignored, mode 0600)   |

The `.adk/` directory also contains generated types, build artifacts, and logs. It's fully gitignored.

## Secrets

Secrets store sensitive values like API keys, passwords, and tokens. They are declared in `agent.config.ts` and their values are stored locally, separate from your code.

### Declaring secrets

Add secrets to your config:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
secrets: {
  OPENAI_KEY: { description: "OpenAI API key" },
  SENTRY_DSN: { optional: true, description: "Error tracking DSN" },
},
```

Required secrets (the default) are enforced at deploy time. `adk dev` warns you if they're unset, but doesn't block the dev server from starting. Optional secrets never block deployment.

### Setting values

You can set values using `adk secret:set` command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk secret:set OPENAI_KEY "sk-..."
adk secret:set OPENAI_KEY "sk-prod-..." --prod
```

Development and production values are stored in separate buckets inside `.adk/secrets.json`. Setting a development value never touches production values, and vice versa.

<Tip>
  Check out the [CLI reference](/docs/adk/cli-reference#configuration-and-secrets) for full documentation of the `adk secret` command.
</Tip>

### Using secrets at runtime

To use secrets at runtime, just import `secrets` from `@botpress/runtime` and reference them directly:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { secrets } from "@botpress/runtime"

const res = await fetch("https://api.openai.com/v1/chat/completions", {
  headers: { Authorization: `Bearer ${secrets.OPENAI_KEY}` },
})

if (secrets.SENTRY_DSN) {
  Sentry.init({ dsn: secrets.SENTRY_DSN })
}
```

The `secrets` import is a typed proxy over environment variables. Required secrets are typed as `string`, optional ones as `string | undefined`.

<Note>
  Secrets are read-only at runtime. Attempting to reassign the value of a secret will throw an error.
</Note>

### Managing secrets in the dev console

You can also manage secrets from the dev console under **Settings > Secrets**. The UI lets you add, edit, and delete secrets for both development and production environments. Schema changes (adding or removing declarations) write back to `agent.config.ts`.

<Frame>
  <img alt="Secrets management in dev console" />

  <img alt="Secrets management in dev console" />
</Frame>

### Naming rules

Secret keys must be `SCREAMING_SNAKE_CASE`:

* Start with an uppercase letter
* At least 2 characters
* No trailing underscore
* Cannot start with `SECRET_`, `BP_`, or `BOTPRESS_` (reserved)

### How secrets flow to production

**Development secrets**: If you're running your agent with `adk dev` and save changes to your development secrets via the dev console, your agent will immediately restart using the new values.

**Production secrets**: If you save changes to your production secrets via the dev console, the changes will only write to `agent.config.ts`. The new values will take effect on your production agent the next time you run `adk deploy`.

## Configuration

The `configuration` object in `agent.config.ts` defines static, deploy-time settings for your agent. Unlike secrets, configuration values are not sensitive. Unlike state, they are read-only at runtime.

### Declaring a schema

Define your schema in `agent.config.ts`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
configuration: {
  schema: z.object({
    supportEmail: z.string().default("help@example.com"),
    maxRetries: z.number().default(3),
    enableBeta: z.boolean().default(false),
  }),
},
```

### Setting values

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk config                                        # Validate and fill missing values interactively
adk config:set supportEmail "help@mycompany.com"   # Set a dev value
adk config:set supportEmail "help@mycompany.com" --prod  # Set a prod value
adk config:get supportEmail                        # Read a value
```

Configuration values can also be managed from the dev console:

<Frame>
  <img alt="Config variables in dev console" />

  <img alt="Config variables in dev console" />
</Frame>

### Using configuration at runtime

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { configuration } from "@botpress/runtime"

const email = configuration.supportEmail
const retries = configuration.maxRetries
```

Configuration is read-only. Attempting to set a value at runtime throws an error.

## Preflight checks

Run `adk check` to validate your project without starting the dev server:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk check
```

This checks:

* Node.js version compatibility
* Runtime version compatibility
* Project structure and primitives
* Generated type assets

Preflight checks also run automatically during `adk dev` and `adk deploy`.


# Integrations
Source: https://botpress.com/docs/adk/setup/integrations

Connect your agent to channels and external services.

Integrations connect your agent to the outside world. They provide channels (Webchat, Slack, WhatsApp) and external services (Gmail, Linear, Stripe).

## Adding integrations

The dev console has a built-in integration hub. Browse the full catalog and install any integration straight into your project, no CLI needed:

<Frame>
  <img alt="Integrations page in dev console" />

  <img alt="Integrations page in dev console" />
</Frame>

## Configuring integrations

Most integrations need configuration (API keys, tokens, webhook URLs) before they can run. Open an installed integration in the dev console to fill in its settings:

<Frame>
  <img alt="Integration configuration in dev console" />

  <img alt="Integration configuration in dev console" />
</Frame>

Integration configuration is stored directly on Botpress' servers, not in your local project files. This differs from your agent's secrets, which your code reads directly.

Your development bot and production bot each have their own configuration, so you can use different API keys or settings per environment.

## Enabling and disabling

Newly added integrations are disabled by default. You can enable them from the dev console, or switch to the object form in `agent.config.ts` and set `enabled: true`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
dependencies: {
  integrations: {
    webchat: {
      version: "webchat@latest",
      enabled: true,
    },
  },
},
```

To disable an enabled integration without removing it, set `enabled: false`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
dependencies: {
  integrations: {
    slack: {
      version: "slack@latest",
      enabled: false,
    },
  },
},
```

Disabled integrations are still part of your project (types are generated, code can reference them) but they won't be active when your agent runs. You can also toggle this from the dev console.

## Managing integrations using the CLI

You can also manage integrations from the command line:

| Command                          | What it does                                                   |
| -------------------------------- | -------------------------------------------------------------- |
| `adk search <query>`             | Search the Botpress Hub for integrations                       |
| `adk list --available`           | List all available integrations                                |
| `adk info <name>`                | Show details, actions, events, and channels for an integration |
| `adk add <name>`                 | Add an integration to your project                             |
| `adk add <name> --alias <alias>` | Add with a custom alias                                        |
| `adk upgrade <name>`             | Update an integration to a newer version                       |
| `adk remove <name>`              | Remove an integration from your project                        |

Newly added integrations are disabled by default. You can enable and configure them in the dev console.

<Note>
  For full documentation on managing integrations via the command line, check out the [CLI reference](/docs/adk/cli-reference).
</Note>

## Integration versions

Here's the syntax for referencing integration versions:

| Format                   | Example                     | Behavior                              |
| ------------------------ | --------------------------- | ------------------------------------- |
| `name@latest`            | `webchat@latest`            | Resolves to the newest version        |
| `name@version`           | `slack@0.5.0`               | Pins to a specific version            |
| `workspace/name@version` | `my-workspace/custom@1.0.0` | Uses a workspace-specific integration |

Use `@latest` during development. Pin to specific versions for production deployments.


# Agent steps
Source: https://botpress.com/docs/adk/testing/agent-steps

See what your agent did during each conversation turn in real time.

Agent Steps is a panel in the dev console **Chat** view that shows you exactly what happened during each conversation turn. While you chat with your agent on the left, the right panel shows a live breakdown of every action the agent took to produce its response.

<Frame>
  <img alt="Agent Steps panel in dev console" />

  <img alt="Agent Steps panel in dev console" />
</Frame>

## What it shows

For each turn, Agent Steps displays:

* **User message** that triggered the turn
* **Tool calls** with input and output for each tool the model called
* **Knowledge searches** showing which queries ran and what passages matched
* **LLM reasoning** including the code the model generated
* **Messages sent** back to the user
* **Errors** if anything failed during execution
* **Duration** for each step and the total turn

Each item is expandable. Click on a tool call to see its full input and output. Click on a knowledge search to see the matched passages and their scores.

## When to use it

Agent Steps is the fastest way to debug during development. Use it when:

* The agent gives a wrong answer and you want to see which tool it called (or didn't call)
* You want to verify the agent is using your knowledge base correctly
* A tool call fails and you need to see the error
* You want to understand the model's reasoning path
* You're tuning instructions and want to see how changes affect behavior

## Traces link

Each turn in Agent Steps links to its full trace in the **Traces** view. Click the trace link to see the complete span timeline with detailed telemetry. See [Debug with logs and traces](/docs/adk/testing/debugging) for more on the Traces view.


# Debug with logs and traces
Source: https://botpress.com/docs/adk/testing/debugging

Inspect traces, spans, and logs to understand what your agent is doing.

The ADK provides two observability views in the dev console and a CLI command for reading logs.

## Traces

The **Traces** view in the dev console shows a timeline of every span in your agent's execution. Each conversation turn, workflow step, tool call, and LLM request is captured as a span with timing and metadata.

<Frame>
  <img alt="Traces view in dev console" />

  <img alt="Traces view in dev console" />
</Frame>

### What you can see

* **Handler spans** showing conversation and workflow handler execution
* **Autonomous execution** spans for each `execute()` call, including iteration count and model used
* **Tool call spans** with input, output, and duration
* **LLM call spans** with model, token usage, and latency
* **Knowledge search spans** with queries and result counts
* **Error spans** with stack traces

### Filtering

Filter traces by time range, span type, or search for specific content. Click any span to expand its details and see its child spans.

## Logs

The **Logs** view in the dev console shows structured log output from your agent. Any `console.log`, `console.warn`, or `console.error` from your handlers, tools, and actions appears here.

<Frame>
  <img alt="Logs view in dev console" />

  <img alt="Logs view in dev console" />
</Frame>

### CLI

You can also read logs from the command line:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk logs                         # Show recent logs
adk logs --follow                # Stream logs in real time
adk logs error                   # Errors only
adk logs warning since=1h        # Warnings and errors from the last hour
adk logs limit=100               # Last 100 entries
```

The positional filter tokens are `error` / `warning` / `info` (cumulative level), `since=<duration>`, and `limit=<n>`. See the [CLI reference](/docs/adk/cli-reference#adk-logs) for all flags.

Logs are stored in `.adk/logs/` while the dev server is running.


# Write and run evals
Source: https://botpress.com/docs/adk/testing/evals

Automated conversation tests for your agent.

Evals are automated tests that simulate conversations with your agent and assert on the results. You write a conversation script with expected behaviors, and the eval runner plays it against your running agent and reports pass/fail.

## Create an eval

Create `.eval.ts` files in the `evals/` directory at your agent root:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Eval } from "@botpress/runtime"

export default new Eval({
  name: "greeting",
  description: "Agent should greet the user",
  conversation: [
    {
      user: "Hello",
      assert: {
        response: [
          { llm_judge: "The response is a friendly greeting" },
        ],
      },
    },
  ],
})
```

Each file can export one or more `Eval` instances as the default export or named exports.

## Conversation turns

An eval's `conversation` is a sequence of turns. Each turn can send a user message, fire an event, or assert the agent stays silent, plus optionally assert on what happens.

Send user messages:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
conversation: [
  {
    user: "What's the weather in Paris?",
    assert: {
      response: [{ contains: "Paris" }],
      tools: [{ called: "getWeather", params: { city: { equals: "Paris" } } }],
    },
  },
  {
    user: "And in London?",
    assert: {
      response: [{ contains: "London" }],
    },
  },
]
```

Fire an event instead of a message:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  event: {
    type: "order.placed",
    payload: { orderId: "ord-123", total: 49.99 },
  },
  assert: {
    response: [{ contains: "order" }],
  },
}
```

Assert the agent doesn't respond:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  user: "ok thanks",
  expectSilence: true,
}
```

## Assertions

Each turn's `assert` block can hold any combination of the assertion types below.

### Response

Assert on the text of the agent's reply:

| Assertion                   | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `{ contains: "text" }`      | Response includes this string                                                          |
| `{ not_contains: "text" }`  | Response does not include this string                                                  |
| `{ matches: "regex" }`      | Response matches this regex pattern                                                    |
| `{ similar_to: "text" }`    | Response is semantically similar to this text                                          |
| `{ llm_judge: "criteria" }` | An LLM evaluates whether the response meets the criteria (see [LLM judge](#llm-judge)) |

### Tools

Assert on which tools the agent called:

| Assertion                                                      | Description                              |
| -------------------------------------------------------------- | ---------------------------------------- |
| `{ called: "toolName" }`                                       | Tool was called                          |
| `{ called: "toolName", params: { key: { equals: "value" } } }` | Tool was called with matching parameters |
| `{ not_called: "toolName" }`                                   | Tool was not called                      |
| `{ call_order: ["tool1", "tool2"] }`                           | Tools were called in this order          |

Use these operators inside `params` to match tool arguments:

| Operator                   | Example                 |
| -------------------------- | ----------------------- |
| `{ equals: value }`        | Exact match             |
| `{ contains: "text" }`     | String contains         |
| `{ not_contains: "text" }` | String does not contain |
| `{ matches: "regex" }`     | Regex match             |
| `{ in: [1, 2, 3] }`        | Value is in array       |
| `{ exists: true }`         | Field exists            |
| `{ gte: 10 }`              | Greater than or equal   |
| `{ lte: 100 }`             | Less than or equal      |

### State

Assert on state changes after a turn:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
assert: {
  state: [
    { path: "messageCount", changed: true },
    { path: "topic", equals: "weather" },
  ],
}
```

### Tables

Assert on table data:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
assert: {
  tables: [
    { table: "OrderTable", row_exists: { userId: { equals: "user123" } } },
    { table: "OrderTable", row_count: { gte: 1 }, where: { status: { equals: "pending" } } },
  ],
}
```

### Workflows

Assert on workflow state:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
assert: {
  workflow: [
    { name: "processOrder", entered: true },
    { name: "processOrder", completed: true },
  ],
}
```

### Timing

Assert on response time:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
assert: {
  timing: [
    { response_time: { lte: 5000 } },
  ],
}
```

### LLM judge

Use `llm_judge` when the right answer isn't a fixed string. You describe what a good response looks like in plain English, and an LLM scores the agent's reply against it. It's the right choice for subjective checks like tone, intent, or whether the agent understood the user:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
assert: {
  response: [
    { llm_judge: "The response is polite and professional" },
    { llm_judge: "The response correctly identifies the user's issue" },
  ],
}
```

Configure the judge model and pass threshold under [Configure eval behavior](#configure-eval-behavior).

## Setup and outcome

`setup` runs before the first turn. `outcome` runs after the last.

### Setup

Seed state or trigger a workflow before the conversation starts:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
new Eval({
  name: "returning-user",
  setup: {
    state: {
      user: { name: "Alice", visitCount: 5 },
      conversation: { topic: "billing" },
    },
  },
  conversation: [
    {
      user: "Hi",
      assert: {
        response: [{ contains: "Alice" }],
      },
    },
  ],
})
```

Trigger a workflow instead of (or in addition to) seeding state:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
setup: {
  workflow: {
    trigger: "onboarding",
    input: { userId: "user123" },
  },
},
```

### Outcome

Assert on state, tables, or workflows after the entire conversation completes. Outcome assertions use the same shapes as turn assertions:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
new Eval({
  name: "full-flow",
  conversation: [
    { user: "Create a ticket for VPN issues" },
    { user: "Set priority to high" },
  ],
  outcome: {
    tables: [
      { table: "TicketTable", row_exists: { priority: { equals: "high" } } },
    ],
    workflow: [
      { name: "createTicket", completed: true },
    ],
  },
})
```

## Configure eval behavior

Set defaults for all evals in `agent.config.ts`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
evals: {
  judgeModel: "openai:gpt-4o",
  judgePassThreshold: 3,
  idleTimeout: 15000,
},
```

| Option               | Type           | Description                                                    |
| -------------------- | -------------- | -------------------------------------------------------------- |
| `judgeModel`         | `string`       | Model for `llm_judge` assertions. Defaults to `"fast"`         |
| `judgePassThreshold` | `number` (1–5) | Minimum score for `llm_judge` to pass. Defaults to `3`         |
| `idleTimeout`        | `number` (ms)  | How long to wait for the agent to respond. Defaults to `15000` |

Override `judgePassThreshold` or `idleTimeout` on a specific eval:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
new Eval({
  name: "quality-check",
  options: {
    judgePassThreshold: 4,
    idleTimeout: 30000,
  },
  conversation: [/* ... */],
})
```

## Organize evals

Evals have two organizing fields that pair with CLI filters: `tags` and `type`.

**Tags** are free-form labels. Use them to group evals you want to run together (smoke tests, critical paths, slow suites):

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
new Eval({
  name: "greeting",
  tags: ["smoke", "core"],
  conversation: [/* ... */],
})
```

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk evals --tag smoke    # Run only evals tagged "smoke"
```

**Type** marks what the eval is for:

* `capability`: tests that a feature works as designed
* `regression`: reproduces a past bug so it doesn't come back

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
new Eval({
  name: "fix-for-ticket-priority-bug",
  type: "regression",
  conversation: [/* ... */],
})
```

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk evals --type regression    # Run only regression evals
```

## Run evals

From the CLI:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk evals                        # Run all evals
adk evals greeting               # Run a specific eval by name
adk evals --tag smoke            # Run evals with a specific tag
adk evals --type regression      # Run only regression evals
adk evals -v                     # Show full details, not just failures
```

View past runs:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk evals runs                   # List recent runs
adk evals runs --latest          # Show the latest run
adk evals runs <run-id>          # Show a specific run
```

You can also run and view evals from the dev console under **Evals**.

<Frame>
  <img alt="Evals page in dev console" />

  <img alt="Evals page in dev console" />
</Frame>


# Run scripts
Source: https://botpress.com/docs/adk/testing/scripts

Execute TypeScript scripts with full access to your agent's runtime context.

`adk run` executes a TypeScript script with the ADK runtime fully initialized. Your script can use all of your agent's primitives, integrations, and runtime utilities like `client`, `actions`, `bot`, and `user`.

## Basic usage

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk run scripts/seed-data.ts
adk run scripts/migrate.ts --prod
adk run scripts/report.ts arg1 arg2
```

## Writing a script

Your script exports a function that the runner calls:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// scripts/seed-data.ts
import { actions } from "@botpress/runtime"
import OrderTable from "../src/tables/order-table"

export default async function () {
  await OrderTable.createRows({
    rows: [
      { userId: "user-1", total: 99.99, status: "pending" },
      { userId: "user-2", total: 149.99, status: "completed" },
    ],
  })

  console.log("Seed data created")
}
```

The runner looks for exports in this order:

1. `export default function`
2. `export function run`
3. `export function main`
4. Top-level code (runs on import)

## Arguments

Extra arguments after the script path are passed to your function. Positional arguments pass through directly; put flag-like arguments (anything starting with `-`) after a `--` separator so Commander doesn't try to parse them:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk run scripts/process.ts order-123
adk run scripts/process.ts -- --limit 100 --verbose
```

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default async function (...args: string[]) {
  console.log(args)  // ["order-123"] or ["--limit", "100", "--verbose"]
}
```

## Production mode

By default, scripts run against your dev bot. Use `--prod` to run against the production bot:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk run scripts/migrate.ts --prod
```

## Use cases

* **Seed data** into tables for development or testing
* **Run migrations** to update table schemas or transform data
* **Generate reports** by querying tables and knowledge bases
* **Maintenance tasks** like cleaning up old data or re-indexing
* **Test actions** by calling them directly outside a conversation


# Create workflows
Source: https://botpress.com/docs/adk/workflows/create

Build long-running background processes that run independently of conversations.

Workflows handle multi-step operations that run in the background. Unlike conversations, which respond to user messages, workflows run independently and can be scheduled, started programmatically, or triggered by the AI model.

Use workflows for things like data processing pipelines, scheduled tasks, multi-step operations that need retries, or any work that shouldn't block a conversation.

## Creating a workflow

Create a file in `src/workflows/`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow, z } from "@botpress/runtime"

export default new Workflow({
  name: "processOrder",
  description: "Process a new customer order",
  input: z.object({
    orderId: z.string(),
  }),
  output: z.object({
    status: z.string(),
    total: z.number(),
  }),
  handler: async ({ input, step }) => {
    const order = await step("fetch-order", async () => {
      return await fetchOrder(input.orderId)
    })

    await step("charge-payment", async () => {
      await chargePayment(order)
    })

    return { status: "completed", total: order.total }
  },
})
```

The `input` and `output` schemas define what the workflow accepts and returns. Both use Zod.

View running and completed workflows, their status, input, output, and run history from the dev console:

<Frame>
  <img alt="Workflows page in dev console" />

  <img alt="Workflows page in dev console" />
</Frame>

### Persistent state

Add a `state` schema to carry data across the workflow's steps and retries. State is persisted between executions:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Workflow({
  name: "importJob",
  state: z.object({
    processed: z.number().default(0),
    lastId: z.string().optional(),
  }),
  handler: async ({ state, step }) => {
    await step("process-batch", async () => {
      state.processed += 100
      state.lastId = "batch-end"
    })
  },
})
```

## Starting a workflow

### Programmatically

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import ProcessOrderWorkflow from "../workflows/processOrder"

const instance = await ProcessOrderWorkflow.start({ orderId: "12345" })
console.log("Started workflow:", instance.id)
```

### On a schedule

Use a cron expression to run a workflow on a recurring schedule:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Workflow({
  name: "dailyReport",
  description: "Generate and send a daily summary",
  schedule: "0 9 * * *",
  handler: async ({ step }) => {
    const data = await step("gather-data", async () => {
      return await gatherDailyMetrics()
    })

    await step("send-report", async () => {
      await sendSlackMessage(formatReport(data))
    })
  },
})
```

Common cron patterns:

| Expression       | Schedule                 |
| ---------------- | ------------------------ |
| `"0 9 * * *"`    | Every day at 9:00 AM     |
| `"0 */6 * * *"`  | Every 6 hours            |
| `"*/30 * * * *"` | Every 30 minutes         |
| `"0 0 * * 1"`    | Every Monday at midnight |

### As a tool

Convert a workflow to a tool so the AI model can start it during `execute()`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Conversation } from "@botpress/runtime"
import ProcessOrderWorkflow from "../workflows/processOrder"

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are an order management assistant.",
      tools: [ProcessOrderWorkflow.asTool()],
    })
  },
})
```

## Deduplication

Use `getOrCreate()` to avoid starting duplicate workflows:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const instance = await ProcessOrderWorkflow.getOrCreate({
  key: "order-12345",
  input: { orderId: "12345" },
  statuses: ["pending", "in_progress"],
})
```

If a workflow with the same key and one of the specified statuses already exists, it returns the existing instance instead of creating a new one. `statuses` defaults to `["pending", "in_progress", "listening", "paused"]` if you don't pass it.

## Loading a workflow by ID

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow } from "@botpress/runtime"

const instance = await Workflow.get("workflow-id")
```

## Workflow instance

When you start a workflow, you get an instance with these methods:

### Cancel

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await instance.cancel()
```

### Set timeout

Extend or change the workflow timeout:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await instance.setTimeout({ in: "30m" })
await instance.setTimeout({ at: "2025-01-15T12:00:00Z" })
```

### Complete early

End the workflow from inside the handler with a result:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Workflow({
  name: "myWorkflow",
  output: z.object({ result: z.string() }),
  handler: async ({ workflow }) => {
    workflow.complete({ result: "done early" })
  },
})
```

### Fail from inside the handler

Mark the workflow as failed with a reason. This throws immediately and interrupts the handler:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
handler: async ({ input, workflow }) => {
  if (!input.orderId) {
    workflow.fail("Missing order ID")
  }
}
```

### Run autonomous execute

Run the AI model inside the workflow, same as in conversations:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
handler: async ({ workflow, step }) => {
  await step("classify", async () => {
    return await workflow.execute({
      instructions: "Classify this ticket as 'bug' or 'feature'.",
    })
  })
}
```

## Timeout

Workflows time out after 5 minutes by default. Use the `timeout` prop to change this:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Workflow({
  name: "longProcess",
  timeout: "1h",
  handler: async ({ step }) => {
    // ...
  },
})
```

For workflows that need to run longer than 5 minutes, use [steps](/docs/adk/workflows/steps). Steps break the work into persisted checkpoints so the workflow can resume from the last completed step.

## Handler parameters

| Parameter  | Type          | Description                                                                                       |
| ---------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `input`    | `object`      | Validated input matching the workflow's input schema                                              |
| `state`    | `object`      | Mutable workflow state, persisted across executions                                               |
| `step`     | `function`    | Step function for persistence and control flow                                                    |
| `client`   | `object`      | Botpress client for API calls                                                                     |
| `execute`  | `function`    | Run the AI model (same as in conversations)                                                       |
| `signal`   | `AbortSignal` | Indicates when the workflow should stop                                                           |
| `workflow` | `object`      | Current workflow instance (id, name, tags, `cancel`, `complete`, `fail`, `setTimeout`, `execute`) |


# Request and notify from workflows
Source: https://botpress.com/docs/adk/workflows/request-notify

Exchange data between workflows and conversations.

Workflows run in the background, but sometimes they need input from the user or want to send progress updates to the conversation. Requests and notifications are the bridge between workflows and conversations.

## Requests

A request pauses the workflow and asks the conversation for data. The workflow defines what it needs, the conversation handler collects it from the user and sends it back to the workflow.

### Define requests in the workflow

Declare the request schemas in the workflow definition:

```typescript highlight={5-14} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow, z } from "@botpress/runtime"

export default new Workflow({
  name: "orderWorkflow",
  requests: {
    orderId: z.object({
      orderId: z.string(),
    }),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      zip: z.string(),
    }),
  },
  handler: async ({ step }) => {
    const orderData = await step.request("orderId", "Please provide the order ID.")

    const address = await step.request("shippingAddress", "Where should we ship this?")

    await step("process", async () => {
      await processOrder(orderData.orderId, address)
    })
  },
})
```

`step.request()` pauses the workflow and sends a `workflow_request` event to the conversation. The first argument is the name of the data being requested, and the second argument is a natural language prompt for that data.

### Handle requests in the conversation

When a workflow makes a request, the conversation handler receives it as `type: "workflow_request"`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Conversation({
  channel: "webchat.channel",
  handler: async (props) => {
    if (props.type === "workflow_request") {
      if (props.request.type === "orderWorkflow:orderId") {
        await props.request.workflow.provide(
          "orderId",
          { orderId: "ORD-12345" },
          props.request.step
        )
      }

      if (props.request.type === "orderWorkflow:shippingAddress") {
        await props.request.workflow.provide(
          "shippingAddress",
          { street: "123 Main St", city: "Springfield", zip: "62701" },
          props.request.step
        )
      }
      return
    }

    await props.execute({ instructions: "You are a helpful assistant." })
  },
})
```

The `request.type` is formatted as `"workflowName:requestName"`. Use `request.workflow.provide()` to send the data back, passing `request.step` as the third argument so the workflow knows exactly which pending step to resume. Omitting it works when only one step is pending for that request, but throws an error if multiple are pending. The workflow resumes once the data is provided.

### Let the AI handle requests

You can also let `execute()` handle workflow requests by passing them as context:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (props.type === "workflow_request") {
  await props.execute({
    instructions: `A workflow needs information from the user. Ask them: ${props.request.type}`,
  })
  return
}
```

## Notifications

A notification sends data from the workflow to the conversation without pausing the workflow. Use it for progress updates, status changes, or any information the user should see while the workflow keeps running.

### Define notifications in the workflow

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow, z } from "@botpress/runtime"

export default new Workflow({
  name: "importWorkflow",
  notifications: {
    progress: z.object({
      message: z.string(),
      percentage: z.number(),
    }),
  },
  handler: async ({ step }) => {
    await step.notify("progress", { message: "Starting import...", percentage: 0 })

    await step("import-data", async () => {
      await importBatch1()
    })

    await step.notify("progress", { message: "50% complete", percentage: 50 }, "progress-50")

    await step("import-remaining", async () => {
      await importBatch2()
    })

    await step.notify("progress", { message: "Import complete!", percentage: 100 }, "progress-100")
  },
})
```

The third argument to `step.notify()` is an optional step name. Use unique step names when sending the same notification type multiple times from one handler.

### Handle notifications in the conversation

Notifications arrive as `type: "workflow_notify"`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Conversation({
  channel: "webchat.channel",
  handler: async (props) => {
    if (props.type === "workflow_notify") {
      const { message, percentage } = props.notification.payload
      await props.conversation.send({
        type: "text",
        payload: { text: `${message} (${percentage}%)` },
      })
      return
    }

    await props.execute({ instructions: "You are a helpful assistant." })
  },
})
```

## Workflow callbacks

When a workflow completes (successfully or with failure), the conversation receives a `workflow_callback` event:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (props.type === "workflow_callback") {
  const { status, output } = props.completion
  if (status === "completed") {
    await props.conversation.send({
      type: "text",
      payload: { text: `Workflow finished: ${JSON.stringify(output)}` },
    })
  }
  return
}
```


# Use workflow steps
Source: https://botpress.com/docs/adk/workflows/steps

Break workflows into persisted, resumable checkpoints.

By default, workflows time out after 5 minutes. Steps let you break a workflow into a series of checkpoints that are persisted individually. If a workflow is interrupted, it resumes from the last completed step.

## Basic steps

The `step` function takes a unique name and a handler. The return value is persisted and reused if the step has already completed:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new Workflow({
  name: "dataPipeline",
  handler: async ({ step }) => {
    const data = await step("fetch-data", async () => {
      return await fetchDataFromAPI()
    })

    const processed = await step("process-data", async () => {
      return processData(data)
    })

    await step("store-results", async () => {
      await saveResults(processed)
    })
  },
})
```

Step names should be unique. If the same name runs twice, the second call returns the first one's cached result instead of running.

Steps can be nested. A parent step completes when all its sub-steps complete.

## Retries

Steps retry automatically on failure. Control the number of attempts with `maxAttempts` (defaults to 5):

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const data = await step("fetch-data", async ({ attempt }) => {
  console.log(`Attempt #${attempt}`)
  return await fetchDataFromAPI()
}, { maxAttempts: 10 })
```

If a step exhausts all retries, it throws an error. This fails the entire workflow unless you catch it:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
try {
  await step("risky-operation", async () => {
    return await unstableAPICall()
  }, { maxAttempts: 3 })
} catch (err) {
  console.log("Operation failed after 3 attempts:", err)
}
```

## Sleep

Pause the workflow for a duration (in milliseconds) or until a specific time:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await step.sleep("wait-5-min", 5 * 60 * 1000)

await step.sleepUntil("wait-until-noon", new Date("2025-01-15T12:00:00Z"))
```

The workflow is suspended during sleep, and no further compute is used.

## Progress

Use `.progress()` to record a checkpoint without running any work. This is useful for observability when you want to mark milestones in a long handler:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await step.progress("Started import")
// ...
await step.progress("Halfway done")
// ...
await step.progress("Finished")
```

## Listen

Use `.listen()` to suspend the workflow and set its status to `"listening"`. The workflow then waits to be resumed by an external event. You can specify this event by passing its name in as an argument:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await step.listen("wait-for-payment")
```

## Fail and abort

Use `.fail()` or `.abort()` to stop execution explicitly:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Mark as failed with a message
await step.fail("User verification required")

// Abort immediately without marking as failed
step.abort()
```

## Child workflows

You can start another workflow and wait for it to complete:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import ProcessingWorkflow from "../workflows/processing"

const result = await step.executeWorkflow(
  "process-data",
  ProcessingWorkflow,
  { data: inputData }
)
```

Or wait for an already-running workflow:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const childWorkflow = await ChildWorkflow.start({})
const result = await step.waitForWorkflow("wait-for-child", childWorkflow.id)
```

## Parallel processing

### `map`

Process an array of items in parallel and collect results:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const results = await step.map(
  "process-users",
  users,
  async (user, { i }) => await processUser(user),
  { concurrency: 5, maxAttempts: 3 }
)
```

### `forEach`

Process items in parallel without collecting results:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await step.forEach(
  "notify-users",
  users,
  async (user) => await sendNotification(user),
  { concurrency: 10 }
)
```

### `batch`

Process items in sequential batches:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await step.batch(
  "bulk-insert",
  records,
  async (batch) => await database.bulkInsert(batch),
  { batchSize: 100 }
)
```


# Classify, validate and filter
Source: https://botpress.com/docs/adk/zai/classify

Check conditions, label content, filter, sort, rate, and group items.

Zai provides methods for classifying, validating, and organizing data using an LLM.

## Check a condition

`zai.check()` asks the LLM a yes/no question about some input and returns `true` or `false`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { adk } from "@botpress/runtime"

const emailBody = "Click here for a FREE iPhone! Limited time only!!!"
const isSpam = await adk.zai.check(emailBody, "is this spam?")
// true
```

Call `.result()` for the Boolean plus the LLM's reasoning:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { output } = await adk.zai.check(emailBody, "is this spam?").result()
// output.value       → true
// output.explanation → "The message uses urgency tactics and promises free rewards..."
```

## Label content

`zai.label()` applies multiple Boolean labels to content:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const result = await adk.zai.label(emailBody, {
  spam: "is this email spam?",
  urgent: "does this require immediate attention?",
  promotional: "is this promotional content?",
})
// { spam: true, urgent: false, promotional: true }
```

## Filter an array

`zai.filter()` keeps items that match a condition:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const comments = [
  "Great product, I love it!",
  "This is terrible spam content",
  "Very helpful review, thank you",
]

const clean = await adk.zai.filter(comments, "is not spam or inappropriate")
// ["Great product, I love it!", "Very helpful review, thank you"]
```

## Sort items

`zai.sort()` orders items using natural language criteria:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const tasks = [
  "Update documentation",
  "Fix critical security bug",
  "Add new feature",
  "System is down - all users affected",
]

const prioritized = await adk.zai.sort(tasks, "by urgency and impact, most urgent first")
// ["System is down...", "Fix critical security bug", "Add new feature", "Update documentation"]
```

## Rate items

`zai.rate()` scores items on a 1-5 scale. Pass a string for a single criterion:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const reviews = [
  "Amazing product! Best purchase ever!",
  "It's okay, nothing special",
  "Terrible quality, broke immediately",
]

const ratings = await adk.zai.rate(reviews, "Rate the sentiment")
// [5, 3, 1]
```

Pass an object to score each item across multiple criteria. Each result includes a `total`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const essays = ["... first essay ...", "... second essay ..."]

const ratings = await adk.zai.rate(essays, {
  grammar: "Rate the grammar and spelling",
  clarity: "Rate how clear and well-organized the writing is",
  argumentation: "Rate the strength of arguments and evidence",
})
// [
//   { grammar: 4, clarity: 5, argumentation: 3, total: 12 },
//   { grammar: 3, clarity: 4, argumentation: 4, total: 11 },
// ]
```

## Group items

`zai.group()` categorizes items into groups. With just `instructions`, it discovers groups on its own:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const messages = [
  "I can't log in to my account",
  "How do I reset my password?",
  "When will my order arrive?",
  "The app keeps crashing",
]

const groups = await adk.zai.group(messages, {
  instructions: "Group by type of customer issue",
})
// { "Login Issues": [...], "Shipping Questions": [...], "Technical Errors": [...] }
```

To force items into predefined categories, pass `initialGroups`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const articles = [
  "How to build a React app",
  "Python machine learning tutorial",
  "Understanding Docker containers",
]

const groups = await adk.zai.group(articles, {
  instructions: "Categorize by technology",
  initialGroups: [
    { id: "frontend", label: "Frontend Development" },
    { id: "backend", label: "Backend Development" },
    { id: "ml", label: "Machine Learning" },
  ],
})
```

| Option             | Type                 | Description                                                                           |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------- |
| `instructions`     | `string`             | How to group the items                                                                |
| `initialGroups`    | `Array<{id, label}>` | Predefined categories to use instead of discovering them                              |
| `maxGroups`        | `number`             | Upper limit on groups. Smaller groups merge at the end until within the limit         |
| `minElements`      | `number`             | Minimum items per group. Groups below the threshold have their elements redistributed |
| `tokensPerElement` | `number`             | Max tokens per item                                                                   |
| `chunkLength`      | `number`             | Max tokens per chunk for large inputs                                                 |


# Extract structured data
Source: https://botpress.com/docs/adk/zai/extract

Pull typed data from unstructured text using an LLM.

`zai.extract()` takes unstructured text and a schema, and returns typed structured data. The LLM reads the text and fills in the schema fields.

## Basic usage

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { adk, z } from "@botpress/runtime"

const product = await adk.zai.extract(
  "Blueberries are $3.99 and are in stock.",
  z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  })
)
// { name: "blueberries", price: 3.99, inStock: true }
```

## Complex schemas

Extract nested objects and arrays:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const order = await adk.zai.extract(
  `Order #1234 from John Smith (john@example.com):
   - 2x Widget ($10 each)
   - 1x Gadget ($25)
   Shipping to 123 Main St, Springfield, IL 62701`,
  z.object({
    orderId: z.string(),
    customer: z.object({
      name: z.string(),
      email: z.string(),
    }),
    items: z.array(z.object({
      name: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
    })),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      state: z.string(),
      zip: z.string(),
    }),
  })
)
```

## Example: classifying emails

`extract()` works anywhere in your agent. Here it's used inside a workflow step to parse and classify incoming emails:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Workflow, adk, z } from "@botpress/runtime"

export default new Workflow({
  name: "processEmails",
  handler: async ({ step }) => {
    const emails = await step("fetch-emails", async () => {
      return await fetchUnreadEmails()
    })

    const parsed = await step("parse-emails", async () => {
      return Promise.all(emails.map(email =>
        adk.zai.extract(email.body, z.object({
          intent: z.enum(["support", "sales", "billing", "other"]),
          urgency: z.enum(["low", "medium", "high"]),
          summary: z.string(),
        }))
      ))
    })
  },
})
```


# Generate text and summaries
Source: https://botpress.com/docs/adk/zai/generate

Generate, rewrite, summarize, and answer questions with citations.

Zai provides methods for generating and transforming text. Each method handles prompting and output formatting.

## Generate text

`zai.text()` generates content from a prompt:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { adk } from "@botpress/runtime"

const intro = await adk.zai.text(
  "Write a brief introduction about AI in customer service",
  { length: 200 }
)
```

| Option   | Type     | Description             |
| -------- | -------- | ----------------------- |
| `length` | `number` | Target length in tokens |

## Rewrite text

`zai.rewrite()` transforms text based on instructions:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const formal = await adk.zai.rewrite(
  "hey, the meeting is tmrw at 3",
  "Make this professional and formal"
)
// "The meeting has been scheduled for tomorrow at 3:00 PM."
```

| Option     | Type                                    | Description                              |
| ---------- | --------------------------------------- | ---------------------------------------- |
| `length`   | `number`                                | Max tokens to generate                   |
| `examples` | `Array<{input, output, instructions?}>` | Few-shot examples to guide the rewriting |

## Summarize

`zai.summarize()` condenses long content. It handles documents from a few paragraphs up to entire books by chunking and merging automatically:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const summary = await adk.zai.summarize(longArticle, {
  length: 100,
  prompt: "Focus on key findings and conclusions",
})
```

| Option               | Type                  | Description                                                                                            |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
| `length`             | `number`              | Target summary length in tokens                                                                        |
| `prompt`             | `string`              | Instructions for what to focus on                                                                      |
| `format`             | `string`              | How to format the output (e.g. "bullet points with clear sections")                                    |
| `intermediateFactor` | `number`              | How many times longer intermediate summaries are than the final length (used for very large documents) |
| `maxIterations`      | `number`              | Max refinement passes                                                                                  |
| `sliding`            | `{ window, overlap }` | Override the default chunk size and overlap                                                            |

## Answer with citations

`zai.answer()` answers a question from a set of documents and tells you which documents backed the answer. It doesn't always return a direct answer: if the question is ambiguous, off-topic, or the documents don't cover it, the result carries that information instead.

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const faq = [
  "Orders ship within 2 business days. Standard shipping takes 3-5 business days; expedited takes 1-2.",
  "Returns are accepted within 30 days of delivery. Items must be unused and in original packaging.",
  "Our warranty covers manufacturing defects for 1 year from purchase. Wear and tear is not covered.",
]

const result = await adk.zai.answer(faq, "How long do I have to return something?")

if (result.type === "answer") {
  console.log(result.answer)     // "Returns are accepted within 30 days of delivery..."
  console.log(result.citations)  // Points back to the returns policy entry
}
```

Branch on `result.type` to handle the other cases (ambiguous questions, off-topic, etc.):

| Type                | Fields                              | When it's returned                                     |
| ------------------- | ----------------------------------- | ------------------------------------------------------ |
| `answer`            | `answer`, `citations`               | The documents support a clear answer                   |
| `ambiguous`         | `ambiguity`, `follow_up`, `answers` | The question has multiple valid interpretations        |
| `out_of_topic`      | `reason`                            | The question isn't covered by the documents' topic     |
| `invalid_question`  | `reason`                            | The question is malformed or nonsensical               |
| `missing_knowledge` | `reason`                            | The topic is relevant but the documents don't cover it |

## Patch files

`zai.patch()` makes surgical edits to code or text files based on natural language instructions. It produces minimal diffs rather than regenerating entire files:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const files = [{
  path: "src/utils.ts",
  name: "utils.ts",
  content: 'export function add(a: number, b: number) {\n  return a + b\n}',
}]

const patched = await adk.zai.patch(
  files,
  "Add JSDoc comments to all exported functions"
)
```


# Introduction to Zai
Source: https://botpress.com/docs/adk/zai/overview

Type-safe LLM utilities for common AI operations.

Zai is a utility library for structured LLM operations. Instead of writing raw prompts, you call typed methods like `extract()`, `check()`, `summarize()`, and `text()` that handle prompting, parsing, and validation for you.

In the ADK, Zai is available via `adk.zai`. It automatically uses your agent's configured `zai` model from `defaultModels` in `agent.config.ts`.

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { adk } from "@botpress/runtime"

const zai = adk.zai
```

## What you can do

| Method        | What it does                                | Page                                               |
| ------------- | ------------------------------------------- | -------------------------------------------------- |
| `extract()`   | Pull structured data from unstructured text | [Extract structured data](/docs/adk/zai/extract)        |
| `check()`     | Verify a Boolean condition                  | [Classify, validate and filter](/docs/adk/zai/classify) |
| `label()`     | Categorize content with multiple labels     | [Classify, validate and filter](/docs/adk/zai/classify) |
| `filter()`    | Filter an array by a condition              | [Classify, validate and filter](/docs/adk/zai/classify) |
| `sort()`      | Sort items using natural language criteria  | [Classify, validate and filter](/docs/adk/zai/classify) |
| `rate()`      | Rate items on a 1-5 scale                   | [Classify, validate and filter](/docs/adk/zai/classify) |
| `group()`     | Group items into categories                 | [Classify, validate and filter](/docs/adk/zai/classify) |
| `text()`      | Generate text from a prompt                 | [Generate text and summaries](/docs/adk/zai/generate)   |
| `rewrite()`   | Transform text based on instructions        | [Generate text and summaries](/docs/adk/zai/generate)   |
| `summarize()` | Summarize long content                      | [Generate text and summaries](/docs/adk/zai/generate)   |
| `answer()`    | Answer questions with citations             | [Generate text and summaries](/docs/adk/zai/generate)   |
| `patch()`     | Make surgical edits to files                | [Generate text and summaries](/docs/adk/zai/generate)   |

## Quick example

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { adk, z } from "@botpress/runtime"

const zai = adk.zai

const product = await zai.extract(
  "Blueberries are $3.99 and are in stock.",
  z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  })
)
// { name: "blueberries", price: 3.99, inStock: true }
```

## Model configuration

Zai uses the `zai` model from `defaultModels` in `agent.config.ts`:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
defaultModels: {
  autonomous: "cerebras:gpt-oss-120b",
  zai: "cerebras:gpt-oss-120b",
},
```

You can also change the model from the dev console under **Settings > LLM Config**.

## Method categories

<CardGroup>
  <Card title="Extract structured data" icon="braces" href="/adk/zai/extract">
    Pull typed data from unstructured text.
  </Card>

  <Card title="Generate text and summaries" icon="sparkles" href="/adk/zai/generate">
    Generate, rewrite, summarize, and answer with citations.
  </Card>

  <Card title="Classify, validate and filter" icon="tags" href="/adk/zai/classify">
    Check conditions, label content, filter, sort, rate, and group.
  </Card>
</CardGroup>


# Concepts
Source: https://botpress.com/docs/api-reference/admin-api/concepts



The **Admin API** is used to manage the surrounding infrastructure of the bots. It handles accounts, workspaces, users, quotas, billing, and other administrative functions.

## Account

An **Account** represents a customer entity using the system. It can be an organization or an individual user. Accounts manage billing, workspaces, and quotas.

* Each account has one or more workspaces.
* Quotas and billing are managed at the account level.

***

## Workspace

A **Workspace** is an isolated environment within an account where users, bots, and integrations operate. Workspaces help segment data and configurations.

* Each workspace belongs to a single account.
* Users can have access to multiple workspaces.
* Contains its own configurations, bots, and logs.

***

## Workspace Member

A **Workspace Member** is a user who has access to a workspace. Each member has a role that defines their level of access.

* Roles control permissions for actions like managing bots or settings.
* Members can belong to multiple workspaces with different roles.
* Access can be managed via the Admin API.

***

## Billing

**Billing** manages the invoicing and payments for workspaces, tracking charges for resources and services consumed. It ensures that workspaces are billed accurately based on usage and helps admins manage unpaid invoices.

* Workspaces receive invoices for services and usage. These can be listed and reviewed.
* The API provides details on upcoming invoices, allowing for proactive management.
* Administrators can trigger payments for unpaid invoices, including tracking which invoices were successfully charged or failed.

***

## Quotas

**Quotas** define usage limits for accounts and workspaces. These limits may apply to API requests, storage, or bot execution.

* Enforced per account, workspace, or bot, depending on the resource type.
* Some quotas are adjustable based on subscription plans.
* API responses may include quota-related headers or errors when limits are exceeded.

### Common Quotas

* **AI Usage**: Limits AI spend and website indexing.
* **Bot Limits**: Caps number of bots, invocations, and always-alive bots.
* **Integrations & Actions**: Restricts billable actions and owned integrations.
* **Workspace Limits**: Controls members and general usage quotas.
* **Storage**: Limits tables and total rows.

***

## Bot

**Bots** are automated entities that perform tasks within a workspace. They interact with users, execute Workflows, and process data.

* Manage bots throughout their lifecycle within a workspace with the Admin API.
* Track and manage different versions of a bot, including deploying a specific version.
* Generate and retrieve code for embedding bots into web interfaces via webchat.

***

## Integration

**Integrations** allow bots to connect with external systems, enabling them to interact with third-party services such as Slack or WhatsApp. By connecting bots to these external platforms, integrations extend the bot's functionality and enable more complex Workflows.

Integrations can be:

* **Public**: These are pre-built integrations developed by Botpress for widely used services (like Slack).
* **Private**: Custom integrations built for specific workspaces, allowing for connections to internal systems or specialized third-party services. You can manage those using the Admin API.

***

## Activity

**Activities** are key events and actions in the system, primarily related to bot behavior and interactions. These logs help monitor and debug the actions bots take, including messages, tasks, and errors. Activity logs serve as an audit trail for understanding bot actions and system events over time.

* Tracks events such as bot-user interactions, task status changes, and system errors.
* Useful for monitoring bot performance and diagnosing issues.
* Helps provide transparency into bot behavior and actions within the system.

***

## Logs

**Logs** capture detailed records of activity for both bots and integrations. These logs encompass system-level events as well as user-generated log entries, such as those created using `console.log` or `logger.log`.

***

## Issues

**Issues** track problems or errors affecting a bot’s functionality. These can be analyzed and resolved to ensure the bot operates smoothly. **Issue events** provide context and detail about what occurred during a specific issue.

***

## Analytics

**Analytics** focus on the performance and usage data of bots. They provide insights into how a bot is performing over time and can be used to track key metrics within a specified time range.

***

For detailed API specifications, refer to the API reference documentation.


# Getting started
Source: https://botpress.com/docs/api-reference/admin-api/getting-started



The Admin API allows administrators to manage users, settings, and logs within the platform. This guide will help you quickly get up and running with the API.

## Prerequisites

Before using the Admin API, make sure you have the following:

* **Token**: You must generate a token to authenticate your requests. The details for obtaining and using your token are explained in our [Authorization Guide](../authentication).
* **Workspace ID**: Each API request requires the `x-workspace-id` header to specify the workspace you're operating on. Ensure you have the correct workspace ID.

All API requests will be made to endpoints under this URL.

## Two Ways to Interact with the API

There are two ways to interact with the Admin API: using **HTTP requests** or the **Botpress client**. Choose the one that fits your needs.

### Option 1: Using HTTP Requests

You can interact with the Admin API directly through HTTP requests. The base URL for the Admin API is:

```http theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
https://api.botpress.cloud/v1/admin
```

All API requests will be made to endpoints under this URL. You must include your token in the `Authorization` header as a Bearer token. In addition to the token, you will have to include the `x-workspace-id` header in each API request. This header specifies the workspace that the request is for.

Here's an example of how to fetch a list of bots:

#### Example: Fetching bots

To fetch a list of bots, send a GET request to `/bots`. Here's an example using `curl`:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X GET "https://api.botpress.cloud/v1/admin/bots" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

This will return a JSON object containing a list of bots.

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "bots": [
    {
      "id": "string",
      "createdAt": "2025-04-03T19:25:44.810Z",
      "updatedAt": "2025-04-03T19:25:44.810Z",
      "name": "string",
      "deployedAt": "2025-04-03T19:25:44.810Z"
    }
  ],
  "meta": {
    "nextToken": "string"
  }
}
```

### Option 2: Using the Botpress Client

Alternatively, you can use the [Botpress client](https://www.npmjs.com/package/@botpress/client) to interact with the Admin API programmatically. This is ideal for integrating the Admin API within your application.

#### Installation

To install the Botpress client:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install @botpress/client
```

#### Example: Fetching Workspaces with the Client

After installing the client, you can instantiate it with your token and workspace ID, then use it to fetch a bot:

<Note>
  This example uses [`dotenv` ](https://www.npmjs.com/package/dotenv) to manage Botpress credentials. If you'd rather manage your credentials differently, just remove the import and define your token, workspace ID, and bot ID however you like.
</Note>

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

async function main() {
    const token = process.env.TOKEN
    const workspaceId = process.env.WORKSPACE_ID
    const botId = process.env.BOT_ID

    if (!botId) {
        throw new Error('Missing required BOT_ID environment variable')
    }

    console.log(token, workspaceId, botId)

    const client = new Client({
        token,
        workspaceId
    })

    const { bot } = await client.getBot({ id: botId })
    console.log('Bot: ', bot)
}

void main()
```

## Error Handling

In case of errors, the API will return an appropriate [HTTP status code and an error message](../errors). Here are some common errors you might encounter, and why:

* 401 Unauthorized: Your token and/or x-workspace-id is missing or invalid.
* 403 Forbidden: You don't have permission to perform this action.
* 404 Not Found: The requested resource couldn't be found.
* 500 Internal Server Error: Something went wrong on the server side.

### Example: Handling a 401 Unauthorized Error

If you receive a 401 Unauthorized error, check that your token is valid and included in the Authorization header of your request, and that the correct x-workspace-id is provided.

## Quotas/limits

The maximum payload size for the Admin API is .

## Next Steps

Now that you’ve successfully made your first request, you can explore other API endpoints and features. Here are a few things you can do next:

* [View the full list of available endpoints](#).
* [Learn how to manage user permissions through the API](#).
* [Learn how to fetch usage data](#)

## Resources

* [API Reference](#)
* [Authorization Guide](../authentication)
* [Error handling](../errors)


# deleteBot
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/delete-v1adminbots

/admin-openapi.json delete /v1/admin/bots/{id}
Delete bot



# deleteBotIssue
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/delete-v1adminbots-issues

/admin-openapi.json delete /v1/admin/bots/{id}/issues/{issueId}
Delete Bot Issue



# deleteIntegration
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/delete-v1adminintegrations

/admin-openapi.json delete /v1/admin/integrations/{id}
Delete integration



# deleteWorkspaceMember
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/delete-v1adminworkspace-members

/admin-openapi.json delete /v1/admin/workspace-members/{id}
Remove a member of a workspace



# deleteWorkspace
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/delete-v1adminworkspaces

/admin-openapi.json delete /v1/admin/workspaces/{id}
Delete workspace



# getAccount
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminaccountme

/admin-openapi.json get /v1/admin/account/me
Get details of the account authenticating with this endpoint.



# listBots
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots

/admin-openapi.json get /v1/admin/bots
List bots



# getBot
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots-1

/admin-openapi.json get /v1/admin/bots/{id}
Get bot details



# getBotAnalytics
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots-analytics

/admin-openapi.json get /v1/admin/bots/{id}/analytics
Get bot analytics



# getBotIssue
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots-issues

/admin-openapi.json get /v1/admin/bots/{id}/issues/{issueId}
Get Bot Issue



# listBotIssues
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots-issues-1

/admin-openapi.json get /v1/admin/bots/{id}/issues
List Bot Issues



# listBotIssueEvents
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots-issues-events

/admin-openapi.json get /v1/admin/bots/{id}/issues/{issueId}/events
List Events for a Bot Issue



# getBotLogs
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminbots-logs

/admin-openapi.json get /v1/admin/bots/{id}/logs
Get bot logs



# listPublicIntegrations
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminhubintegrations

/admin-openapi.json get /v1/admin/hub/integrations
List public integration



# getPublicIntegration
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminhubintegrations-

/admin-openapi.json get /v1/admin/hub/integrations/{name}/{version}
Get public integration by name and version



# getPublicIntegrationById
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminhubintegrations-1

/admin-openapi.json get /v1/admin/hub/integrations/{id}
Get public integration by Id



# listIntegrations
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminintegrations

/admin-openapi.json get /v1/admin/integrations
List integrations, supports filtering and sorting capabilities



# getIntegrationByName
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminintegrations-

/admin-openapi.json get /v1/admin/integrations/{name}/{version}
Get integration



# getIntegration
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminintegrations-1

/admin-openapi.json get /v1/admin/integrations/{id}
Get integration



# getIntegrationLogs
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminintegrations-logs

/admin-openapi.json get /v1/admin/integrations/{id}/logs
Get integration logs



# listWorkspaceMembers
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspace-members

/admin-openapi.json get /v1/admin/workspace-members
Lists all the members in a workspace



# getWorkspaceMember
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspace-membersme

/admin-openapi.json get /v1/admin/workspace-members/me
Get details of the account authenticating with this endpoint.



# listWorkspaces
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspaces

/admin-openapi.json get /v1/admin/workspaces
List workspaces the user has access to



# getWorkspace
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspaces-1

/admin-openapi.json get /v1/admin/workspaces/{id}
Get workspace details



# getAuditRecords
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspaces-audit-records

/admin-openapi.json get /v1/admin/workspaces/{id}/audit-records
Get the audit records of a workspace, sorted from most recent to oldest.



# getPublicWorkspace
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspaces-public

/admin-openapi.json get /v1/admin/workspaces/{id}/public
Get workspace public details



# listPublicWorkspaces
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/get-v1adminworkspacespublic

/admin-openapi.json get /v1/admin/workspaces/public
List public workspaces



# createBot
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/post-v1adminbots

/admin-openapi.json post /v1/admin/bots
Create bot



# createIntegration
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/post-v1adminintegrations

/admin-openapi.json post /v1/admin/integrations
Create integration



# validateIntegrationCreation
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/post-v1adminintegrationsvalidate

/admin-openapi.json post /v1/admin/integrations/validate
Perform a validation of an integration creation request



# createWorkspaceMember
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/post-v1adminworkspace-members

/admin-openapi.json post /v1/admin/workspace-members
Add a member to the workspace



# createWorkspace
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/post-v1adminworkspaces

/admin-openapi.json post /v1/admin/workspaces
Create workspace



# updateAccount
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/put-v1adminaccountme

/admin-openapi.json put /v1/admin/account/me
Update details of the account associated with authenticated user



# updateBot
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/put-v1adminbots

/admin-openapi.json put /v1/admin/bots/{id}
Update bot



# updateIntegration
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/put-v1adminintegrations

/admin-openapi.json put /v1/admin/integrations/{id}
Update integration



# validateIntegrationUpdate
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/put-v1adminintegrations-validate

/admin-openapi.json put /v1/admin/integrations/{id}/validate
Perform a validation of an integration update request



# updateWorkspaceMember
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/put-v1adminworkspace-members

/admin-openapi.json put /v1/admin/workspace-members/{id}
Update the member of a workspace



# updateWorkspace
Source: https://botpress.com/docs/api-reference/admin-api/openapi/endpoints/put-v1adminworkspaces

/admin-openapi.json put /v1/admin/workspaces/{id}
Update workspace



# Authentication
Source: https://botpress.com/docs/api-reference/authentication



You can authenticate to Botpress's API (`api.botpress.cloud`) as a user, a bot, or an integration. To do so, you'll need to use a token.

<Tip>If you are looking to use the Webchat API or the Chat API to talk to your bot, please refer to the [Chat API documentation](/docs/api-reference/chat-api/introduction) and [Webchat documentation](/docs/webchat/get-started/introduction).</Tip>

### Types of Tokens

#### 1. Personal Access Token (PAT)

<Warning>Be careful, your PAT has the same access you have and can be used to access your data. Keep it safe and never share it with anyone.</Warning>

A Personal Access Token (PAT) can be generated in the **Profile Settings** section of your Botpress account. Once generated, you can use this token as a `Bearer token` to authenticate API requests.

#### 2. Bot Access Key

A Bot Access Key (BAK) is provided to the bot once it's deployed. This token limit the API access to only the actions that the bot can perform. Only the [runtime API](/docs/api-reference/runtime-api/getting-started), [tables API](/docs/api-reference/tables-api/getting-started), and [files API](/docs/api-reference/files-api/getting-started) are available with this token.

#### 3. Integration Access Key

An Integration Access Key (IAK) is provided to the integration once it's deployed. This token limit the API access to only the actions that the integration can perform. Only the [runtime API](/docs/api-reference/runtime-api/getting-started) and [files API](/docs/api-reference/files-api/getting-started) are available with this token.

<Note>If you are looking to self host your integration you can generate your own Integration Access Key instead of using your own PAT.</Note>

***

## Authentication Methods

Once you have your token, you can authenticate your requests to Botpress's API (`api.botpress.cloud`) using one of the following methods:

### 1. Authentication with the API

To authenticate using the API, pass the `Authorization` header with the appropriate token. Here's an example of the request format:

```http theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
GET /api/endpoint
Authorization: Bearer {TOKEN}
```

This header should be included in all requests to the Botpress Cloud API, where `{TOKEN}` is replaced with the actual token you obtained (PAT, Bot Access Key, or Integration Access Key).

### 2. Authentication with the Client

You can also authenticate using the client by providing the `token` when creating a new Client instance:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const token = 'your-token'
const client = new Client({ token })
```

In this example, the `token` you is either a Personal Access Token, Bot Access Key, or Integration Access Key. This will create a Client instance that's authenticated and can be used to interact with the API.


# Chat API Introduction
Source: https://botpress.com/docs/api-reference/chat-api/introduction



The Chat API offers an HTTP API to chat with your bot. It allows you to integrate Botpress into a server application (in contrast with [Webchat](/docs/webchat/get-started/introduction), which allows you to integrate Botpress with your website).

<Note>
  The Chat API is only available via an integration built by Botpress. Because of this, all users, conversations and messages created using the Chat API belong to the Chat integration.

  This means you can't use the Chat API to fetch conversations that occur within other integrations, like WhatsApp or Webchat. For that, check out the [Runtime API](../runtime-api/getting-started).
</Note>

## Installation

To use this API, make sure the [Chat integration](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01JVYWESY3BVAM5FR3XT9X813H\&search=Chat+integration) is installed to your bot. Then, make sure your integration is enabled and configured.

## Configuration

The Chat Integration has no required configuration—you can use it as-is. However, it does expose a few options:

* **Encryption Key:** Used to verify incoming requests. If you set this field, you are then responsible for signing the `x-user-key` header yourself. Check out the [Authentication](#authentication) section for more information.

* **Webhook URL:** Called by the Chat API to notify you of chat-related events. The standard way of listening to Chat API events is by opening an SSE stream—if you set this field, you will receive events both on the SSE stream and on the webhook. Check out the \[real time]\(#real time) section for more information.

* **Webhook Secret:** Only used if you set a webhook URL. Included in requests sent to your webhook to ensure that requests made to your webhook are coming from the Chat API.

## Getting Started

To use the Chat API:

1. Find your webhook ID. You can find it in the Chat Integration's configuration page:

<img />

The webhook ID is the string at the end of the **Webhook URL**. In this case, the webhook ID starts with **90** and ends with **51**:

2. Check if you can reach the API by sending a GET request on `https://chat.botpress.cloud/$YOUR_WEBHOOK_ID/hello`.

3. Create a chat user (this isn't the same as a user in your Botpress Dashboard) by calling the [`createUser`](/docs/api-reference/chat-api/openapi/createUser) operation.

   <Note>
     This operation won't be available if you are using manual authentication. Check out the [Authentication](#authentication) section for more information.
   </Note>

4. In the response's body you will find a user key. Copy this key.

5. Create a conversation with your bot by calling the [`createConversation`](/docs/api-reference/chat-api/openapi/createConversation) operation. You will need to provide a user key to authenticate yourself.

6. Send a message to your bot by calling the [`createMessage`](/docs/api-reference/chat-api/openapi/createMessage) operation. You will need to provide:

   * A user key to authenticate yourself
   * A conversation ID to specify which conversation you are sending the message to
   * A message payload. For example, a simple text message has the following payload format: `{ "type": "text", "text": "hello bot" }`.

7. Wait for your bot to respond, then list messages on the conversation by calling the [`listMessages`](/docs/api-reference/chat-api/openapi/listMessages) operation. You will need to provide:

   * A user key to authenticate yourself
   * A conversation ID to specify which conversation you are listing the messages from.

## Authentication

All requests sent to the Chat Integration's API are authenticated with a `x-user-key` header. There are two ways to get this user key:

* You call the `createUser` operation and get the key in the response's body. This operation is the only one that isn't authenticated.
* You can sign it yourself.

We refer to the second method as manual authentication. Use this method to ensure that only you can chat with your bot over the Chat API.

### How to sign your requests manually

To sign your requests yourself, you must choose:

* A **user ID**. This can be any valid string, as long as it's not already taken by another user.

2. An **encryption key**. This can be any valid string. You must set this key in the Chat integration's [configuration](#configuration). This is so the integration knows that you are using manual authentication.

The `x-user-key` header is a [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token). Here's how to sign it using the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) NodeJS library:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const jwt = require('jsonwebtoken')
const YOUR_USER_ID = '$YOUR_USER_ID'
const YOUR_ENCRYPTION_KEY = '$YOUR_ENCRYPTION_KEY'
const xUserKey = jwt.sign({ id: YOUR_USER_ID }, YOUR_ENCRYPTION_KEY, { algorithm: 'HS256' })
```

When handling an incoming request, the Chat Integration will detect that you are using manual authentication and will use your encryption key to verify the `x-user-key` JWT header. If the signature is invalid, the request will be rejected with an unauthorized status code.

By manually signing your requests, you ensure that nobody except you can chat with your bot over the Chat API.

<Warning>
  ### Limitation to manual authentication

  When using manual authentication, calling [`createUser`](/docs/api-reference/chat-api/openapi/createUser) will result in an error response. When needed, call [getOrCreateUser](/docs/api-reference/chat-api/openapi/getOrCreateUser) instead.
</Warning>

## Real time

The Chat API offers two ways of listening to chat events in real time:

1. [Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events), which is the standard way.
2. Webhooks, or HTTP callback URLs.

### Server-Sent Events

To listen to chat-related events on an SSE stream, you must call the [`listenConversation`](/docs/api-reference/chat-api/openapi/listenConversation) operation. This operation will open an SSE stream that you can listen to.

## Official JavaScript Client

There is an [official JavaScript client for the Chat API](https://www.npmjs.com/package/@botpress/chat). It's by far the most convenient way to interact with the Chat API. We strongly recommend using it.

Features:

* Strongly typed operation inputs and outputs.
* Handled manual authentication if you pass an encryption key and user ID.
* Uses an SSE client to listen to conversation events.

## Quotas/limits

The maximum payload size for the Chat API is .


# addParticipant
Source: https://botpress.com/docs/api-reference/chat-api/openapi/addParticipant

chat-openapi.json POST /conversations/{conversationId}/participants
Add a [Participant](#schema_user) to a [Conversation](#schema_conversation).



# createConversation
Source: https://botpress.com/docs/api-reference/chat-api/openapi/createConversation

chat-openapi.json POST /conversations
Creates a new [Conversation](#schema_conversation)



# createEvent
Source: https://botpress.com/docs/api-reference/chat-api/openapi/createEvent

chat-openapi.json POST /events
Creates a custom [Event](#schema_event)



# createMessage
Source: https://botpress.com/docs/api-reference/chat-api/openapi/createMessage

chat-openapi.json POST /messages
Creates a new [Message](#schema_message)



# createUser
Source: https://botpress.com/docs/api-reference/chat-api/openapi/createUser

chat-openapi.json POST /users
Creates a new [User](#schema_user). This operation can only be called when using the shared encryption key.



# deleteConversation
Source: https://botpress.com/docs/api-reference/chat-api/openapi/deleteConversation

chat-openapi.json DELETE /conversations/{id}
Permanently deletes a [Conversation](#schema_conversation). It cannot be undone. Also immediately deletes corresponding [Messages](#schema_message).



# deleteMessage
Source: https://botpress.com/docs/api-reference/chat-api/openapi/deleteMessage

chat-openapi.json DELETE /messages/{id}
Permanently deletes a [Message](#schema_message). It cannot be undone.



# deleteUser
Source: https://botpress.com/docs/api-reference/chat-api/openapi/deleteUser

chat-openapi.json DELETE /users/me
Permanently deletes a [User](#schema_user). It cannot be undone.



# getConversation
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getConversation

chat-openapi.json GET /conversations/{id}
Retrieves the [Conversation](#schema_conversation) object for a valid identifier.



# getEvent
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getEvent

chat-openapi.json GET /events/{id}
Retrieves the [Event](#schema_event) object for a valid identifier.



# getMessage
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getMessage

chat-openapi.json GET /messages/{id}
Retrieves the [Message](#schema_message) object for a valid identifier.



# getOrCreateConversation
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getOrCreateConversation

chat-openapi.json POST /conversations/get-or-create
Get or create a new [Conversation](#schema_conversation)



# getOrCreateUser
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getOrCreateUser

chat-openapi.json POST /users/get-or-create
Get or create a new [User](#schema_user)



# getParticipant
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getParticipant

chat-openapi.json GET /conversations/{conversationId}/participants/{userId}
Retrieves a [Participant](#schema_user) from a [Conversation](#schema_conversation).



# getUser
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getUser

chat-openapi.json GET /users/me
Retrieves the [User](#schema_user) object for a valid identifier.



# listConversations
Source: https://botpress.com/docs/api-reference/chat-api/openapi/listConversations

chat-openapi.json GET /conversations
Returns a list of [Conversation](#schema_conversation) objects



# listMessages
Source: https://botpress.com/docs/api-reference/chat-api/openapi/listMessages

chat-openapi.json GET /conversations/{conversationId}/messages
Retrieves the conversation's [Messages](#schema_message)



# listParticipants
Source: https://botpress.com/docs/api-reference/chat-api/openapi/listParticipants

chat-openapi.json GET /conversations/{conversationId}/participants
Retrieves a list of [Participants](#schema_user) for a given [Conversation](#schema_conversation).



# listenConversation
Source: https://botpress.com/docs/api-reference/chat-api/openapi/listenConversation

chat-openapi.json GET /conversations/{id}/listen
Creates a SSE stream to receive messages and events from a conversation



# removeParticipant
Source: https://botpress.com/docs/api-reference/chat-api/openapi/removeParticipant

chat-openapi.json DELETE /conversations/{conversationId}/participants/{userId}
Remove a [Participant](#schema_user) from a [Conversation](#schema_conversation).



# updateUser
Source: https://botpress.com/docs/api-reference/chat-api/openapi/updateUser

chat-openapi.json PUT /users/me
Update [User](#schema_user)



# Errors
Source: https://botpress.com/docs/api-reference/errors



## Error Response Types

When an error occurs while calling an API endpoint, the response will return the appropriate HTTP status code as indicated below. The following table outlines possible error type and its corresponding description and status.

| **Error Type**               | **Description**                                                                                                                                                                     | **Status Code** |
| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |
| **Unauthorized**             | The request requires authentication.                                                                                                                                                | 401             |
| **Forbidden**                | The requested action can't be performed by this resource.                                                                                                                           | 403             |
| **Payload Too Large**        | The request payload is too large.                                                                                                                                                   | 413             |
| **Invalid Payload**          | The request payload is invalid.                                                                                                                                                     | 400             |
| **Unsupported Media Type**   | The request is invalid because the content-type isn't supported.                                                                                                                    | 415             |
| **Method Not Found**         | The requested method doesn't exist.                                                                                                                                                 | 405             |
| **Resource Not Found**       | The requested resource doesn't exist.                                                                                                                                               | 404             |
| **Invalid JSON Schema**      | The provided JSON schema is invalid.                                                                                                                                                | 400             |
| **Invalid Data Format**      | The provided data doesn't respect the provided JSON schema.                                                                                                                         | 400             |
| **Invalid Identifier**       | The provided identifier isn't valid. An identifier must start with a lowercase letter, be between 2 and 100 characters long and use only alphanumeric characters.                   | 400             |
| **Relation Conflict**        | The resource is related to a different resource than the one referenced in the request. This is usually caused when providing two resource identifiers that aren't linked together. | 409             |
| **Reference Constraint**     | The resource can't be deleted because it's referenced by another resource.                                                                                                          | 409             |
| **Reference Not Found**      | The provided resource reference is missing. This is usually caused when providing an invalid id inside the payload of a request.                                                    | 400             |
| **Invalid Query**            | The provided query is invalid. This is usually caused when providing an invalid parameter for querying a resource.                                                                  | 400             |
| **Runtime**                  | An error happened during the execution of a runtime (bot or integration).                                                                                                           | 400             |
| **Already Exists**           | The record attempted to be created already exists.                                                                                                                                  | 409             |
| **Rate Limited**             | The request has been rate-limited.                                                                                                                                                  | 429             |
| **Payment Required**         | A payment is required to perform this request.                                                                                                                                      | 402             |
| **Quota Exceeded**           | The request exceeds the allowed quota. Quotas are a soft limit that can be increased.                                                                                               | 403             |
| **Limit Exceeded**           | The request exceeds the allowed limit. Limits are a hard limit that can't be increased.                                                                                             | 413             |
| **Breaking Changes**         | Request payload contains breaking changes, which aren't allowed for this resource without a version increment.                                                                      | 400             |
| **Resource Locked Conflict** | The resource is current locked and can't be operated on until the lock is released.                                                                                                 | 409             |
| **Unknown**                  | An unknown error occurred                                                                                                                                                           | 500             |
| **Internal**                 | An internal error occurred                                                                                                                                                          | 500             |

### Example JSON Responses:

**Unknown Error**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "Unknown",
  "description": "An unknown error occurred",
  "status": 500
}
```

**Payload Too Large**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "PayloadTooLarge",
  "description": "The request payload is too large.",
  "status": 413
}
```


# Getting started
Source: https://botpress.com/docs/api-reference/files-api/getting-started



The Files API allows you to upload, download, and manage files and searchable documents for your bots and integrations in Botpress Cloud.

Files can be in any text or binary format, and documents (such as PDF, Microsoft Office, HTML, CSV, etc.) can be indexed to be used for semantic search in RAG (Retrieval Augmented Generation) implementations. Files are private by default but can be made publicly accessible through a permanent URL that's unique for each file.

<Warning>
  When uploading a file and linking it to a Knowledge Base, you **must** index the file or else you will get an infinite loading loop when trying to open the file from the Knowledge Base.
</Warning>

## To get started

1. Get familiarized with the different API endpoints available.

2. Review the [instructions on how to authenticate](/docs/api-reference/authentication) with the API.

3. Check out the How-To guides (see left sidebar) for examples on how to use the Files API in different scenarios.

4. Try calling the list files API endpoint as shown below.

### Using cURL

Calling the Files API can be done using any HTTP client, such as `curl`, `axios`, or `fetch`. Here's an example using `curl`:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
token="$YOUR_BOTPRESS_TOKEN"
bot_id="$YOUR_BOT_ID"
# List your bot's files
curl -H "Authorization: bearer $token" -H "x-bot-id: $bot_id" https://api.botpress.cloud/v1/files
```

## Using the Official TypeScript Client

The official TypeScript client is available as an NPM package. You can install it using any of the following command:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install @botpress/client
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install @botpress/client
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add @botpress/client
  ```
</CodeGroup>

Once installed, you can import the client and use it in your TypeScript code:

<Note>
  This example uses [`dotenv` ](https://www.npmjs.com/package/dotenv) to manage Botpress credentials. If you'd rather manage your credentials differently, just remove the import and define your token and bot ID however you like.
</Note>

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

const main = async () => {
    const token = process.env.TOKEN
    const botId = process.env.BOT_ID

    const client = new Client({
        token,
        botId,
    })

    const response = await client.listFiles({})
    console.log(response.files)
}

void main()
```

## Security

### Access Policies

A file can specify a list of special access policies:

* `public_content`: Unauthenticated users can read contents (but not metadata) of the file through a unique permanent URL provided by the API for each file. Without this policy the file URL returned by the API will be temporary and will expire after a short period of time.
* `integrations`: Grants read, search, list access to all integrations of the bot that owns the file.

Specifying the access policies for a file is completely optional and if not specified the file will be private by default and can only be accessed by the bot or integration that created it.

<Warning>
  Important

  If a file was created by a bot (not an integration) all workspace members (except those with Viewer and Billing roles) that have access to the bot will be able to read, update, or delete the file regardless of the access policies specified.
</Warning>

### Permissions

| Principal                                            | Permissions                                                                                                               |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Public (unauthenticated/unauthorized users)          | Can only download files that have the `public_content` access policy.                                                     |
| Bot                                                  | Owns and manages its files with full permissions to access and manage them, regardless of the user that created the file. |
| Integration                                          | Has all permissions on the files that were created by that integration for the bot they're installed on.                  |
| Viewer workspace member                              | Can read, search, and list all files for the bot, regardless of creator, but can't create or delete files.                |
| Developer, Manager or Administrator workspace member | Has all permissions on the bot's files, regardless of creator.                                                            |
| Billing Manager workspace member                     | No permissions on files.                                                                                                  |

<Note>
  Note

  The [List Files](/docs/api-reference/files-api/how-tos/manage-files#listing-existing-files-of-a-bot) API endpoint will filter out files that aren't accessible to the user calling that API endpoint.
</Note>

## Pricing

There are two types of storage: File Storage and Vector DB Storage. All files count toward your workspace's File Storage usage. Indexed files also count toward your workspace's Vector DB Storage usage.

For full details on pricing please check our [Pricing page](https://botpress.com/pricing).

## Quotas/Limits

| Category                   | Limit                                                                                            |
| :------------------------- | :----------------------------------------------------------------------------------------------- |
| Maximum uploaded file size | 1 GB                                                                                             |
| Maximum payload size       |                                                                                                  |
| Rate limits                | [Same as all other endpoints](/docs/studio/guides/advanced/safety/preventing-abuse) of our public API |
| Tags                       | As defined in the Limits and Quotas of Botpress Cloud                                            |
| Search - Query             | 1 KB maximum                                                                                     |
| Search - Results           | Maximum number of results: 50                                                                    |


# Create files
Source: https://botpress.com/docs/api-reference/files-api/how-tos/creating-files



## Creating a file

All files are private by default and can only be accessed by the bot or integration that created them.

### In an Execute Card in your bot

The following code snippet can be put in an Execute Card in your bot to create and upload a file that can be accessed by anyone with the file URL and that will be indexed for semantic search:

> Important: Make sure you have enabled the "Use the Botpress Client" setting in your bot's settings in Botpress Studio in order to have access to the `client` global variable; otherwise, it won't be accessible and you'll get an error.

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const file = await client.uploadFile({
  key: 'optional_prefix/unique_file_name.txt', // Each file needs a unique key under your bot
  content: 'This is a test file',
})
```

Once the code above runs, the URL to download the file will be available in the `file.url` property.

By default the file URL returned will be temporary and change on each request to this endpoint, and will expire after a short period of time and thus shouldn't be stored long-term, but if the file was created with a `public_content` [access policy](/docs/api-reference/files-api/openapi/upsertFile#body-access-policies) then this URL will be permanent and can be stored long-term.

#### Uploading from an existing URL

Or if the file is already available in a URL and you want to download and then upload it to Botpress Cloud you can pass it in the `url` parameter instead of using the `content` parameter:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const file = await client.uploadFile({
  key: 'unique_file_name.pdf', // Each file needs a unique key under your bot
  url: 'https://example.com/test.pdf', // This is the external URL where the file is currently located
})
```

#### Uploading a binary file

If you are dealing with a binary file such as a PDF or Microsoft Office document you can also pass a `Buffer` object as the `content` parameter for the file:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const buffer = // This must be a Buffer object containing the binary content of the file

const file = await client.uploadFile({
  key: 'unique_file_name.pdf', // Each file needs a unique key under your bot
  content: buffer,
})
```

### In a custom script using the Botpress Client

If you're using JavaScript or TypeScript, the easiest way to interact with the API is with the [Botpress Client](https://www.npmjs.com/package/@botpress/client). You can install the client package using your favourite package manager:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install @botpress/client
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install @botpress/client
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add @botpress/client
  ```
</CodeGroup>

The Botpress Client will handle the authentication and other details for you, you just need to provide your Botpress PAT (Personal Access Token) to the client and the ID of the bot that the client will access. If your use-case requires accessing multiple bots, you can define as many client instances as needed (one for each bot).

You can use the following code snippet to create and upload a file in a custom script using the Botpress Client. Note that in the example below your Botpress PAT (Personal Access Token) and bot ID must be defined in the environment variables `BOTPRESS_PAT` and `BOTPRESS_BOT_ID` respectively.

<Note>
  This example uses [`dotenv` ](https://www.npmjs.com/package/dotenv) to manage Botpress credentials. If you'd rather manage your credentials differently, just remove the import and define your token and bot ID however you like.
</Note>

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

const main = async () => {
  const token = process.env.TOKEN
  const botId = process.env.BOT_ID

  const client = new Client({
      token,
      botId,
  })

  const file = await client.uploadFile({
      key: 'optional_prefix/unique_file_name.txt',
      content: 'This is a test file',
  })

  console.log(file)
}

void main()
```

### In a custom script using an HTTP client

If you can't use the Botpress Client (for example: you can't install the package or you're working with a different programming language) you can also use any HTTP client to make requests to the API directly.

Please note that when calling the API directly, an HTTP request to the Botpress API (specifying the file size beforehand) will be needed to create the empty file first, and a separate HTTP request will be needed to upload the file content to the unique upload URL provided in the response of the first request.

Additionally, if you need to access the file URL right away a third request to the "Get File" API endpoint will be needed to get the URL of the file after it has been uploaded.

Here's an example on how to do this using the native `fetch()` function in JavaScript/TypeScript. Note that your Botpress PAT will need to be defined in the environment variable `BOTPRESS_PAT`:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const fileContent = 'Here goes the content of your file'

const buffer = Buffer.from(fileContent)

// Step 1: Create the file in Botpress Cloud.
// Please note that specifying the file size (in raw bytes, not characters) is required when calling this endpoint.
const result = await fetch('https://api.botpress.cloud/v1/files', {
  method: 'PUT',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
  body: JSON.stringify({
    key: 'unique_file_name.txt',
    size: buffer.byteLength,
  }),
})

const response = await result.json()

// Step 2: Upload the file content to the unique upload URL provided for the created file.
await fetch(response.file.uploadUrl, {
  method: 'PUT',
  body: buffer,
})

// The variable below will contain the URL to download the file content uploaded above. If the file was
// created with the 'public_content' access policy it will be a permanent URL that you can store long-term,
// otherwise it will contain a temporary pre-signed URL that expires after a short period of time.
// If you need to get a new URL, you can always use the `getFile` API endpoint.
const downloadUrl = response.file.url
```

## Add a file to a Knowledge Base

To add a file to a [Knowledge Base](/docs/studio/concepts/knowledge-base/introduction), you need to set custom tags when making your request.

Here's an example. Make sure the `index` parameter is set to `true`. Otherwise, you won't be able to open the file in Studio:

<CodeGroup>
  ```ts highlight={10-14} Using the Botpress client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import { Client } from '@botpress/client';

  const client = new Client({
    token: process.env.BOTPRESS_PAT,
    botId: process.env.BOTPRESS_BOT_ID,
  });

  const response = await client.uploadFile({
    "key": "filename.txt",
    "index": true, // Set to true
    "tags": {
      "source": "knowledge-base",
      "kbId": "kb_xxxxxxxxxxxxxxxxxxxxxxxxxx", // Your Knowledge Base ID
      "title": "My file" // Optional title
    },
    "content": fileContent
  });
  ```

  ```ts highlight={17-21} Using an HTTP request theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const token = process.env.BOTPRESS_PAT;
  const botId = process.env.BOTPRESS_BOT_ID;

  const fileContent = 'Your file content';
  const buffer = Buffer.from(fileContent);

  const url = 'https://api.botpress.cloud/v1/files';
  const options = {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'x-bot-id': botId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "key": "filename.txt",
      "index": true, // Set to true
      "tags": {
        "source": "knowledge-base",
        "kbId": "kb_xxxxxxxxxxxxxxxxxxxxxxxxxx", // Your Knowledge Base ID
        "title": "My file", // Optional title
      },
      "size": buffer.byteLength,
    })
  };

  const response = await fetch(url, options);
  const data = await response.json();

  await fetch(data.file.uploadUrl, {
    method: 'PUT',
    body: buffer,
  });
  ```
</CodeGroup>

## Creating a public file

If you need to make a file publicly accessible by anyone you can assign the `public_content` access policy to the file:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const file = await client.uploadFile({
  key: 'test.txt',
  content: 'This is a public file',
  accessPolicies: ['public_content'],
})

// This will be a permanent URL (can be stored long-term) to allow anyone to download the file.
const fileUrl = file.url
```

> Note: Making a file publicly accessible only makes its content public but not its metadata or the ability to modify the file, which remains private. The file will be accessible through a unique permanent URL provided by the API for each file, and this URL can be stored long-term.

If you only want to allow all the integrations installed in the bot to access the file rather than making it fully public, you can just assign the `integrations` access policy instead:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const response = await client.uploadFile({
  key: 'test.txt',
  content: 'This is a public file',
  accessPolicies: ['public_content'],
})

// This will be a permanent URL (can be stored long-term) to allow anyone to download the file.
const fileUrl = response.file.url
```

## Adding tags to a file

You can add custom tags to a file by passing the `tags` parameter when it's created. Tags allow you to organize and classify files in any way you see fit, and can be specified as a filter when listing or searching files.

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const response = await client.uploadFile({
  key: 'test.txt',
  content: 'This is a test file',
  tags: {
    // Tags are optional but are useful for filtering files by a custom criteria you choose when using the "List Files" or "Search Files" API endpoints
    // You can change or remove the tags below based on your needs.
      category: 'Sales',
      knowledgeBaseName: 'Client Questions',
  },
})

console.log(response.file)
```


# Index and search files
Source: https://botpress.com/docs/api-reference/files-api/how-tos/index-and-search-files



## Creating an indexed file

If you need to index a file for semantic search just pass the `index: true` parameter when creating the file.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Client } from '@botpress/client'

const client = new Client({
  token: process.env.BOTPRESS_PAT,
  botId: process.env.BOTPRESS_BOT_ID,
})

const file = await client.uploadFile({
  key: 'test.txt',
  content: 'This is a test file',
  index: true,
})
```

### Supported file formats

The following file formats are supported for indexing:

| Format   | File Extension | MIME Type         |
| -------- | -------------- | ----------------- |
| PDF      | `.pdf`         | `application/pdf` |
| HTML     | `.html`        | `text/html`       |
| Text     | `.txt`         | `text/plain`      |
| Markdown | `.md`          | `text/markdown`   |

### Notes on indexing

* The file it will initially have a status of `indexing_pending` and will be indexed asynchronously. The time it takes to index the file will depend on the file size and the current load on the system.
* You can check the status of the file by calling the [Get File](/docs/api-reference/files-api/how-tos/manage-files#getting-the-file’s-metadata) endpoint and checking that the `file.status` property has changed to `indexing_completed`.
* If the indexing failed the status will be set to `indexing_failed` and the reason of the failure will be available in the `failedStatusReason` property of the file.

## Searching files

To run a semantic search on your bot's files you can use the [Search Files](../openapi/searchFiles) API endpoint. This is particularly useful for RAG (Retrieval Augmented Generation) implementations.

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const res = await client.searchFiles({
    query: 'what are the most popular products of your company?', // This is the natural language query (for example: a user's question) to be used for running a semantic search on the files of the bot.
    contextDepth: 1, // Optional (default: 0), allows you prepend and append the surrounding context to each matching passage in the search results
    tags: {
      // Optional, allows you to only search files that match the specified tags. Useful if you only want to search a subset of the bot's files.
      category: 'Support',
      subcategory: 'Technical',
    },
    limit: 30, // Default is 20, maximum is 50 results
  })

  const passages = res.passages

  for (const passage of passages) {
    // You can use passage.content here to retrieve the content (including surrounding context, if any) of each matching passage
  }
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import qs from 'qs' // You'll need to install this package first using your favorite package manager

  const params = qs.stringify({
    query: 'what are the most popular products of your company?',
    tags: {
      // Optional: You can delimit the search to only files that match the specified tags
      category: 'Support',
      subcategory: 'Technical',
    },
  })

  const result = await fetch('https://api.botpress.cloud/v1/files/search?' + params, {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const passages = response.passages
  ```
</CodeGroup>

You can check the [API reference](../openapi/searchFiles) for more details on the properties available for each passage object returned in the response.

### Using the search results for RAG

You can use the search results to provide relevant information to a bot for generating a response to a user's question.

Here's an example of a simple RAG (Retrieval Augmented Generation) implementation that shows how you can use the ChatGPT large language model (through the OpenAI API) and the search results provided by our API to answer a user's question:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from 'openai' // You'll need to install this package first using your favorite package manager

const openai = new OpenAI({ apiKey: 'YOUR_OPENAI_API_KEY' })) // Change this for your own OpenAI API key

const userQuestion = 'Which are the most popular products of your company?' // This will come from the user's input

const res = await client.searchFiles({
  query: userQuestion,
  contextDepth: 1, // This number can be increased to pass more context to the model for each matching passage
})

const relevantInformation = res.data.passages.map(passage => passage.content).join("\n\n----------\n\n")

const answer = await openai.chat.completions.create({
    model: 'gpt-4o-mini', //  This can be changed for any other OpenAI model available here: https://platform.openai.com/docs/models
    messages: [
        {
            role: 'system',
            // You can change the text below to include any additional instructions to the model
            content: "You are a helpful assistant that answers the user's question based only on the relevant information you are provided along with the question.",
        },
        {
            role: 'user',
            content: `## RELEVANT INFORMATION: \n\n ${relevantInformation}\n\n` +
                     `## ANSWER THE FOLLOWING USER'S QUESTION: \n\n ${userQuestion}`,
        },
    ],
})
```


# Manage files
Source: https://botpress.com/docs/api-reference/files-api/how-tos/manage-files



## Getting the file's metadata

To get the details of a file you can use the [Get File](/docs/api-reference/files-api/how-tos/manage-files#getting-the-file’s-metadata) API endpoint.

You can also use this endpoint to retrieve a new temporary pre-signed URL to download a file if the previous pre-signed URL has already expired.

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import { Client } from '@botpress/client'

  const client = new Client({
    token: process.env.BOTPRESS_PAT,
    botId: process.env.BOTPRESS_BOT_ID,
  })

  const file = await client.getFile({ id: "YOUR_FILE_ID" });
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const result = await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const file = response.file
  ```
</CodeGroup>

## Listing existing files of a bot

To list all the files of a bot you can use the [List Files](/docs/api-reference/files-api/how-tos/manage-files#listing-existing-files-of-a-bot) API endpoint.

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const res = await client.listFiles({})
  const files = res.files
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const result = await fetch('https://api.botpress.cloud/v1/files', {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const files = response.files
  ```
</CodeGroup>

### Filtering by tag values

If you need to filter files by tags, pass in the `tags` parameter, which is an object containing tags as key-value pairs. This will only return files that include all the tags (and corresponding values) that you specify.

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const { files } = await client.listFiles({
    tags: {
      category: 'Sales',
    },
  })
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import qs from 'qs' // You'll need to install this package first using your favorite package manager

  const tags = {
    category: 'Sales',
  }

  const params = qs.stringify({ tags })

  const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const files = response.files
  ```
</CodeGroup>

You can also pass in an array of strings as the tag's value. This returns files that have that tag with any of the specified values:

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const { files } = await client.listFiles({
    tags: {
      category: ['Sales', 'Marketing'],
    },
  })
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import qs from 'qs' // You'll need to install this package first using your favorite package manager

  const tags = {
    category: ['Sales', 'Marketing'],
  }

  const params = qs.stringify({ tags })

  const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const files = response.files
  ```
</CodeGroup>

### Advanced tag filtering

Instead of passing in the value of a tag, you can pass in an object with the `exists`, `not` or `in` properties to allow for more advanced filtering.

#### `exists`

Use the `exists` property to specify whether a tag should be present or absent on the returned files:

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const { files } = await client.listFiles({
    tags: {
      integrationName: {
        exists: false
      }
    }
  })
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import qs from 'qs' // You'll need to install this package first using your favorite package manager

  const tags = {
    integrationName: {
      exists: false
    }
  }

  const params = qs.stringify({ tags })

  const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const files = response.files
  ```
</CodeGroup>

#### `not`

Use the `not` property to specify a value (or an array of values) to exclude for a given tag:

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const { files } = await client.listFiles({
    tags: {
      integrationName: {
        not: 'webchat', // Could be a string or an array of strings
      },
    },
  })
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import qs from 'qs' // You'll need to install this package first using your favorite package manager

  const tags = {
    integrationName: {
      not: 'webchat' // Could be a string or an array of strings
    }
  }

  const params = qs.stringify({ tags })

  const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const files = response.files
  ```
</CodeGroup>

#### `in`

Use the `in` property to specify a value (or an array of values) to include for a given tag:

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const { files } = await client.listFiles({
    tags: {
      integrationName: {
        in: ['webchat', 'whatsapp'], // Could be a string or an array of strings
      },
    },
  })
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import qs from 'qs' // You'll need to install this package first using your favorite package manager

  const tags = {
    integrationName: {
      in: ['webchat', 'whatsapp'] // Could be a string or an array of strings
    }
  }

  const params = qs.stringify({ tags })

  const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
    method: 'GET',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })

  const response = await result.json()
  const files = response.files
  ```
</CodeGroup>

### Pagination

The [List Files](/docs/api-reference/files-api/how-tos/manage-files#listing-existing-files-of-a-bot) API endpoint will return by default the 20 most recent files your bot has. If you need to list older files you can use the `nextToken` property returned in the API response to retrieve the next page (if any) of files. The `nextToken` will be included for each page if there are files remaining to be listed.

For example:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
let res = await client.listFiles({})
const files = res.files

// You can put this in a loop to retrieve all the files if needed
if (res.meta.nextToken) {
  res = await client.listFiles({ nextToken: res.meta.nextToken })
  files.push(...res.files)
}
```

## Updating the file metadata

Only the tags and access policies of a file can be updated.

Here's an example of how to update the access policies and tags of a file using the Botpress Client:

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const response = await client.updateFileMetadata({
    id: 'file_01K86HD0D5T3HFCGBEKQJFNKAD',
    accessPolicies: ['integrations'], // This value will replace the existing access policies of the file.
    tags: {
      // This acts as a "patch" or partial update, so only the tags specified here will be updated, the rest will remain unchanged. If you need to delete an existing tag, you can set it to a `null` value.
      category: 'Support', // This tag will be updated.
      knowledgeBaseName: null, // This tag will be deleted.
      subcategory: 'Technical', // This tag will be added.
      // Any other tags not specified here will remain unchanged.
    },
  })

  const updatedFile = response.file
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
    method: 'PUT',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
    body: {
      accessPolicies: ['integrations'], // This value will replace the existing access policies of the file.
      tags: {
        // This acts as a "patch" or partial update, so only the tags specified here will be updated, the rest will remain unchanged. If you need to delete an existing tag, you can set it to a `null` value.
        category: 'Support', // This tag will be updated.
        knowledgeBaseName: null, // This tag will be deleted.
        subcategory: 'Technical', // This tag will be added.
        // Any other tags not specified here will remain unchanged.
      },
    },
  })
  ```
</CodeGroup>

## Updating file content

If you need to update the content of a file, you can create a new file with the updated content and then delete the old file. The file ID will change in this case.

## Deleting a file

To delete a file you can use the "Delete File" API endpoint.

<CodeGroup>
  ```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  await client.deleteFile({ id: "YOUR_FILE_ID" })
  ```

  ```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
    method: 'DELETE',
    headers: {
      'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
      Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
    },
  })
  ```
</CodeGroup>


# deleteFile
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/delete-v1files

/files-openapi.json delete /v1/files/{id}
Deletes a file.



# listFiles
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/get-v1files

/files-openapi.json get /v1/files
List files for bot



# getFile
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/get-v1files-1

/files-openapi.json get /v1/files/{id}
Get file



# listFilePassages
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/get-v1files-passages

/files-openapi.json get /v1/files/{id}/passages
List passages for a file



# searchFiles
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/get-v1filessearch

/files-openapi.json get /v1/files/search
Search files



# listFileTags
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/get-v1filestags

/files-openapi.json get /v1/files/tags
List available tags



# listFileTagValues
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/get-v1filestags-values

/files-openapi.json get /v1/files/tags/{tag}/values
List available tags



# copyFile
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/post-v1files-

/files-openapi.json post /v1/files/{idOrKey}/{destinationKey}
Copy file



# upsertFile
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/put-v1files

/files-openapi.json put /v1/files
Creates or updates a file using the `key` parameter as unique identifier. Updating a file will erase the existing content of the file. Upload the file content by sending it in a PUT request to the `uploadUrl` returned in the response.



# updateFileMetadata
Source: https://botpress.com/docs/api-reference/files-api/openapi/endpoints/put-v1files-1

/files-openapi.json put /v1/files/{id}
Update file metadata, without updating the file content.



# Introduction
Source: https://botpress.com/docs/api-reference/introduction



At Botpress, we love APIs. Every API we develop—whether public or private—is carefully designed with a strong focus on coherence and consistency. API design is at the core of our development process.

Botpress is also a very big and complex system, and there isn't a single API that does everything. Instead, we provide multiple APIs, each tailored to specific functionalities. Below is a comprehensive list of all publicly available APIs in Botpress. Each API has dedicated documentation section.

Except for the Chat API, all APIs mentioned below are located at the following URL: `https://api.botpress.cloud`.

## Chat API

The Chat API is built on top of the [Chat Integration](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01JVYWESY3BVAM5FR3XT9X813H\&search=Chat+integration) to give you a simple way to interact with your deployed bots via HTTP requests. To use the Chat API in your bot, you first need to install the Chat Integration. The chat API URL is `https://chat.botpress.cloud`. For more details, refer to the [Chat API documentation](./chat-api).

## Admin API

The Admin API allows you to manage your workspace and provides a broad set of functionalities, covering everything from bot creation to monitoring and analytics. Key capabilities include:

* Manage your Bots
* Manage your own private and public integrations
* Fetch Logs, Issues and Analytics
* Update your Workspace Collaborators and Roles
* Manage Workspace Collaborators and Roles

As a general rule, if a feature is available in the Botpress Dashboard, it's likely accessible via the Admin API. For more details, refer to the [Admin API documentation](./admin-api).

## Files API

The Files API allows you to manage any file you or your user uploaded to Botpress. It can be used to upload files used in knowledge bases, to host media files, such as images, videos, and documents, to store files used by your bot, or to store files used by your integration. For more details, refer to the [Files API documentation](./files-api).

## Tables API

The Tables API allows you to manage your tables, which store structured data and offer various features. You can use tables to store user data, automatically label data, and extract information from content. For more details, refer to the [Tables API documentation](./tables-api).

## Runtime API

The Runtime API is for bots and integrations to handle messages, events, and requests. Each request is authenticated as a bot or integration (you can use your [PAT](/docs/api-reference/authentication#1-personal-access-token-pat) to act as either a bot or an integration). For more details, refer to the [Runtime API documentation](./runtime-api).


# Pagination
Source: https://botpress.com/docs/api-reference/pagination



Our APIs return paginated results. Our paging is based on a cursor-based pagination system, which means that the API returns a set of results and a cursor (`nextToken`) that you can use to retrieve the next set of results. You can use this cursor in 2 ways:

## 1. Pagination with API Query Parameters

To retrieve paginated data, you can use the `nextToken` string value returned by the previous request in your next request query parameter.

If your first API request returns the following response:

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "data": [...],
  "meta": {
    "nextToken": "wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g="
  }
}
```

The next request would look like this:

```http theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
GET https://api.botpress.cloud/v1/endpoint?nextToken=wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g=
```

This will return the next set of results. Repeat this process by passing the new `nextToken` until the response body no longer includes a `nextToken` value, indicating that there are no more results.

## 2. Pagination with the Botpress Client

### Using .collect() to Fetch Results

You can also paginate results using the `.collect()` function provided by our client utilities. This is useful when you want to retrieve a specific number of items at once.

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const conversations = await client.list.conversations({}).collect({ limit: 1000 }); // Fetch 1000 conversations
```

The `.collect()` function will handle pagination for you automatically.

### Using Async Generator with for await

If you need to handle pagination in a more granular way, you can use an async generator with the for await syntax. This allows you to iterate over each page one by one.

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
for await (const message of client.list.messages({ type: 'text' })) {
  console.log(message.payload.text);
}
```


# Rate limiting
Source: https://botpress.com/docs/api-reference/ratelimiting



Our APIs are protected using a sliding window rate limiter. This means that exceeding the allowed number of requests per time window will result in a `429 Too Many Requests` (rate-limited) response.

The rate limiter returns for each request the following headers:

* `RateLimit-Limit`: The maximum number of requests allowed in the current time window.
* `RateLimit-Remaining`: The number of requests remaining in the current time window.
* `RateLimit-Reset`: The time at which the current rate limit window will reset in seconds.

For example, if you exceed the rate limit, you will receive the following response:

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "RateLimited",
  "description": "The request has been rate-limited.",
  "status": 429
}
```

### Example Headers

```http theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
RateLimit-Limit: 100
RateLimit-Remaining: 9
RateLimit-Reset: 6
```

When using the official Botpress Client, the rate limiter is automatically handled for you.


# Concepts
Source: https://botpress.com/docs/api-reference/runtime-api/concepts



## Bot

Bots are core entities in the Botpress system, but they aren't accessible through the Runtime API directly. Instead, they're managed via the [Admin API](../admin-api/concepts#bot). Bots are software applications that handle events and messages, responding or acting on them accordingly.

## Integration

Integrations connect Botpress to external services. Like bots, they're not directly accessible from the Runtime API but are managed through the [Admin API](../admin-api/concepts#integration). Integrations handle the sending and receiving of messages, events, and data between Botpress and third-party services. They're defined and managed in the Botpress Admin API.

## Authentication

The Runtime API uses the same authentication mechanism as all other Botpress APIs. For details, refer to the [Authentication documentation](../authentication).

In addition to standard authentication, the Runtime API defines two additional headers that are used to know if requests are made on behalf of a bot or an integration:

* `x-bot-id`: **(Required)** The bot ID targeted by the request. This header is **mandatory** for all Runtime API requests.
* `x-integration-id`: **(Optional)** The ID of the integration making the request. This header is included **only** if the request originates from an integration.

The presence of these headers determines the context of the request:

* **Bot request:** Only `x-bot-id` is provided. The action is performed directly on behalf of the bot.
* **Integration request:** Both `x-bot-id` and `x-integration-id` are provided. The action is performed on behalf of an integration within the specified bot.

<Note>Integrations are only authorized to act within the bots they're installed in. This restriction ensures secure and scoped access to bot data and functionality.</Note>

## Definitions and Instances

Two categories of objects exist in the Botpress Runtime API: **definitions** and **instances**. Each concept listed below is first defined when deploying the integration or bot and then instantiated during the bot or integration execution.

## Message

Messages, just like in any messaging system, are entities that carry information between multiple speakers in a conversation. Integrations define message types and their payload schemas.

Message instances represent actual messages exchanged with the bot or integration. They must conform to the schema defined for their message type by the Integration. Here's the TypeScript representation of a message:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type Message = {
  id: string;
  createdAt: string;
  type: string;
  payload: { [k: string]: any };
  direction: "incoming" | "outgoing";
  userId: string;
  conversationId: string;
  tags: { [k: string]: string };
}
```

### Direction

Each message has a **direction** indicating its source:

* **Incoming**: Originates from an external service (e.g., WhatsApp) and is passed into the Runtime API via the integration.
* **Outgoing**: Generated by the bot and sent to an external service via the integration.

This distinction helps determine whether the message was created by the integration or the bot.

### User and Conversation ID

Messages are always part of a conversation and are associated with a user. Bots are considered users too. The `userId` and `conversationId` track the sender and the conversation context.

### Tags

Tags are key-value pairs used to attach metadata to messages. Only tags defined by the Integration or Bot are permitted.

### Built-in Message Types

Botpress enforces a set of built-in message types that must be supported by integrations:

* **text** A plain text message.
* **image** An image message.
* **audio** An audio message.
* **video** A video message.
* **file** A file message.
* **location** A message indicating a location with a latitude and longitude.
* **carousel** A message containing a carousel of card.
* **card** A message containing an image and a button.
* **dropdown** A message containing a dropdown with options.
* **choice** A message containing a choice with options.
* **bloc** A composite message that can contain multiple message types.

Here's the TypeScript representation of each of these message's payload:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type Text = { text: string }
type Image = { imageUrl: string }
type Audio = { audioUrl: string }
type Video = { videoUrl: string }
type File = {
  fileUrl: string
  title?: string
}
type Location = {
  latitude: number
  longitude: number
  address?: string
  title?: string
}

type Card = {
  title: string
  subtitle?: string
  imageUrl?: string
  actions: {
    action: 'postback' | 'url' | 'say'
    label: string
    value: string
  }[]
}

type Choice = {
  text: string
  options: {
    label: string
    value: string
  }[]
}

type Carousel = {
  items: Card[]
}

type Bloc = {
  items:
    | { type: 'text'; payload: Text }
    | { type: 'image'; payload: Image }
    | { type: 'audio'; payload: Audio }
    | { type: 'video'; payload: Video }
    | { type: 'file'; payload: File }
    | { type: 'location'; payload: Location }
}
```

When an integration is deployed, it can define any message type, but can't override any of the built-in message types with a breaking schema. This means that if an integration defines a message of type `text`, the payload must be compatible with `{ text: string; }`. In other words, it can add type constraints (like new properties) to the payload, but it can't remove them.

## Conversation

A conversation represents the interaction of multiple speakers sending messages. Here's the TypeScript type for a conversation:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type Conversation = {
  id: string;
  createdAt: string;
  updatedAt: string;
  channel: string;
  integration: string;
  tags: { [k: string]: string };
}
```

### Tags

Conversations support tags to store metadata. These tags must be defined in the integration or bot definition. See [Tags](#tags) for more.

### Channel

A conversation belongs to a **channel**, which itself is part of an integration. For example, a GitHub integration might support messaging via issues and pull requests—each of those would be a separate channel. A conversation always occurs on a specific channel of a specific integration.

## User

A user in the Runtime API is a speaker (person or entity) that can send messages in a conversation. Just like conversations, users belong to a specific integration. Interacting with your bot on WhatsApp and Slack will create two different users, even if they both represent the same person with the same email.

<Note>
  Many different kind of users exist in the whole Botpress system. This concept only refer to users of the Runtime API or as we often refer to: Chat Users. It must not be confused with users of the Botpress Admin API which are bot and integration Builders.
</Note>

Here's the user type:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type User = {
  id: string;
  createdAt: string;
  updatedAt: string;
  name?: string;
  pictureUrl?: string;
  tags: { [k: string]: string };
}
```

### Tags

User tags provide metadata and must be defined in the integration or bot definition. See [Tags](#tags) for more.

### Name and Picture URL

The `name` and `pictureUrl` fields are optional and useful for UI or debugging purposes but aren't required for bot functionality.

## Event

Events are another core unit of the Runtime API. Integrations and Bots define event types and payload schemas. Event instances represent real events triggered during execution.

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type Event = {
  id: string;
  createdAt: string;
  type: string;
  payload: { [k: string]: any };
  conversationId?: string;
  userId?: string;
  messageId?: string;
  status: "pending" | "processed" | "ignored" | "failed" | "scheduled";
  failureReason: string | null;
}
```

### Direction

Unlike messages, events have no direction—they're always considered **incoming**. This is because they're always sent to the Bot by either an integration or the bot itself. You may send an event to your bot by an external call to the Runtime API, but doing so still requires you to authenticate as either a bot or an integration.

### Associated IDs

Events can be linked to a conversation, user, or message via their respective IDs. These are optional but helpful for tracking or analytics.

### Status

When an event is created via the Runtime API, it's placed in a queue. The bot processes it asynchronously. The `status` field shows its current processing state.

## State

State is a key-value store for persisting data related to a conversation, user, or other context. Payloads must match the schema defined by the integration or bot.

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type State = {
  id: string;
  createdAt: string;
  updatedAt: string;
  botId: string;
  conversationId?: string;
  userId?: string;
  name: string;
  type: "conversation" | "user" | "bot" | "integration" | "workflow";
  payload: { [k: string]: any };
}
```

### State Names

Each state is identified by a `name`. Bots or integrations can define multiple state types under different names.

### State Types

The `type` indicates what kind of entity the state belongs to. The `integration` type is a misnomer and should be treated as a `bot` type.

## Tags

Tags store string-based metadata for messages, users, and conversations. They're defined by the integration or bot and allow filtering, analytics, or custom logic.

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type Tag = {
  id: string;
  createdAt: string;
  updatedAt: string;
  type: "user" | "conversation" | "message";
  key: string;
  value: string;
}
```

Tags are defined by the integration or bot and can be used to store any additional information that isn't covered by the other properties of the message, user, or conversation objects. Tags are key-value pairs, where both the key and value are strings. The `type` property indicates whether the tag is associated with a user, conversation, or message. It can be used later to filter or search user, conversation, or message objects based on their tags.

Unlike States, Tags are returned with the entity they're linked to. States can be bigger, but must be fetched separately. Also, tags are always string, while states can be any JSON object with a schema defined in the integration or bot definition.

## Actions

Both bots and integrations can define **actions** which are functions with a specific signature. Both integration and bot actions are meant to be called by the bot itself. You may call an action by running an external call to the Runtime API, but doing so, still requires you to authenticate as either a bot. Actions appear as cards in Botpress Studio and are a core way to execute dynamic logic.

## What's Next

Now that API concepts are clear, you can explore [the API reference](./openapi/createConversation).


# Getting Started
Source: https://botpress.com/docs/api-reference/runtime-api/getting-started



The Runtime API is designed for bots and integrations to handle messages, events, actions, and webhook requests at runtime. Each request made to this API is authenticated as either a bot or an integration. It can also be accessed externally by providing a bot or integration ID, though doing so effectively authenticates the request as a bot or integration.

All the endpoints of the Runtime API are located behind the `chat` base path (`api.botpress.cloud/v1/chat/`).

<Warning>
  The Runtime API has many nuances that aren't relevant to bot developers—because of this, we recommend only making your requests using the official [Botpress TypeScript Client](#using-the-official-typescript-client), which simplifies some of the API's trickier aspects.

  If you decide to interact with the Runtime API using another HTTP client, you may experience unintended behaviour or encounter issues.
</Warning>

## Using the Official TypeScript Client

The official TypeScript client is available as an NPM package. You can install it using any of the following command:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install @botpress/client
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install @botpress/client
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add @botpress/client
  ```
</CodeGroup>

Once installed, you can import the client and use it in your TypeScript code:

<Note>
  This example uses [`dotenv` ](https://www.npmjs.com/package/dotenv) to manage Botpress credentials. If you'd rather manage your credentials differently, just remove the import and define your token and bot ID however you like.
</Note>

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

const main = async () => {
    const token = process.env.TOKEN
    const botId = process.env.BOT_ID

    const client = new Client({
        token,
        botId,
    })

    const { messages } = await client.listMessages({})
    console.log(messages)
}

void main()
```

## Quotas/limits

The maximum payload size for the Runtime API is .

## Next Steps

Now that you've successfully made your first request, you can explore other API endpoints and concepts. Here are a few things you can do next:

* [Learn about Runtime API concepts](./concepts)
* [View the full list of available endpoints](./openapi/createConversation).


# deleteConversation
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/delete-v1chatconversations

/runtime-openapi.json delete /v1/chat/conversations/{id}
Permanently deletes a [Conversation](#schema_conversation). It cannot be undone. Also immediately deletes corresponding [Messages](#schema_message).



# removeParticipant
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/delete-v1chatconversations-participants

/runtime-openapi.json delete /v1/chat/conversations/{id}/participants/{userId}
Remove a [Participant](#schema_participant) from a [Conversation](#schema_conversation).



# cancelScheduledEvent
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/delete-v1chateventsscheduled

/runtime-openapi.json delete /v1/chat/events/scheduled/{id}
Permanently cancels a scheduled [Event](#schema_event). The event must be in a `scheduled` state.



# deleteMessage
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/delete-v1chatmessages

/runtime-openapi.json delete /v1/chat/messages/{id}
Permanently deletes a [Message](#schema_message). It cannot be undone.



# deleteUser
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/delete-v1chatusers

/runtime-openapi.json delete /v1/chat/users/{id}
Permanently deletes a [User](#schema_user). It cannot be undone.



# listConversations
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatconversations

/runtime-openapi.json get /v1/chat/conversations
Retrieves a list of [Conversation](#schema_conversation) you’ve previously created. The conversations are returned in sorted order, with the most recent appearing first. The list can be filtered using [Tags](#tags).



# getConversation
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatconversations-1

/runtime-openapi.json get /v1/chat/conversations/{id}
Retrieves the [Conversation](#schema_conversation) object for a valid identifier.



# listParticipants
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatconversations-participants

/runtime-openapi.json get /v1/chat/conversations/{id}/participants
Retrieves a list of [Participant](#schema_participant) for a given [Conversation](#schema_conversation).



# getParticipant
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatconversations-participants-1

/runtime-openapi.json get /v1/chat/conversations/{id}/participants/{userId}
Retrieves a [Participant](#schema_participant) from a [Conversation](#schema_conversation).



# listEvents
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatevents

/runtime-openapi.json get /v1/chat/events
Retrieves a list of [Event](#schema_event) you’ve previously created. The events are returned in sorted order, with the most recent appearing first.



# getEvent
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatevents-1

/runtime-openapi.json get /v1/chat/events/{id}
Retrieves the [Event](#schema_event) object for a valid identifiers.



# listMessages
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatmessages

/runtime-openapi.json get /v1/chat/messages
Retrieves a list of [Message](#schema_message) you’ve previously created. The messages are returned in sorted order, with the most recent appearing first. The list can be filtered using [Tags](/docs/developers/concepts/tags).



# getMessage
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatmessages-1

/runtime-openapi.json get /v1/chat/messages/{id}
Retrieves the [Message](#schema_message) object for a valid identifier.



# getState
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatstates-

/runtime-openapi.json get /v1/chat/states/{type}/{id}/{name}
Retrieves the [State](#schema_state) object for a valid identifiers.



# listTagValues
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chattags-values

/runtime-openapi.json get /v1/chat/tags/{key}/values
Get a bot tag values



# listUsers
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatusers

/runtime-openapi.json get /v1/chat/users
Retrieves a list of [User](#schema_user) previously created. The users are returned in sorted order, with the most recent appearing first. The list can be filtered using [Tags](/docs/developers/concepts/tags).



# getUser
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/get-v1chatusers-1

/runtime-openapi.json get /v1/chat/users/{id}
Retrieves the [User](#schema_user) object for a valid identifier.



# patchState
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/patch-v1chatstates-

/runtime-openapi.json patch /v1/chat/states/{type}/{id}/{name}
Updates the [State](#schema_state) object by setting the values of the parameters passed.



# callAction
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatactions

/runtime-openapi.json post /v1/chat/actions
Call an action



# createConversation
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatconversations

/runtime-openapi.json post /v1/chat/conversations
Creates a new [Conversation](#schema_conversation). When creating a new [Conversation](#schema_conversation), the required tags must be provided. See the specific integration for more details.



# addParticipant
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatconversations-participants

/runtime-openapi.json post /v1/chat/conversations/{id}/participants
Add a [Participant](#schema_participant) to a [Conversation](#schema_conversation).



# getOrCreateConversation
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatconversationsget-or-create

/runtime-openapi.json post /v1/chat/conversations/get-or-create
Retrieves the [Conversation](#schema_conversation) object containing given tags. If the conversation does not exist, it will be created. Tags will be updated if they are set in the request body.



# createEvent
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatevents

/runtime-openapi.json post /v1/chat/events
Creates a new [Event](#schema_event). When creating a new [Event](#schema_event), the required tags must be provided. See the specific integration for more details.



# configureIntegration
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatintegrationsconfigure

/runtime-openapi.json post /v1/chat/integrations/configure
An integration can call this endpoint to configure itself



# createMessage
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatmessages

/runtime-openapi.json post /v1/chat/messages
Creates a new [Message](#schema_message). When creating a new [Message](#schema_message), the required tags must be provided. See the specific integration for more details.



# getOrCreateMessage
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatmessagesget-or-create

/runtime-openapi.json post /v1/chat/messages/get-or-create
Retrieves the [Message](#schema_message) object for given discriminating tags. If the message does not exist, it will be created. If the message already exists, its tags and payload will be updated with the provided values if they are defined.



# setState
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatstates-

/runtime-openapi.json post /v1/chat/states/{type}/{id}/{name}
Overrides the [State](#schema_state) object by setting the values of the parameters passed.



# setStateExpiry
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatstates--expiry

/runtime-openapi.json post /v1/chat/states/{type}/{id}/{name}/expiry
Updates the [State](#schema_state) expiry.



# getOrSetState
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatstates--get-or-set

/runtime-openapi.json post /v1/chat/states/{type}/{id}/{name}/get-or-set
Retrieves the [State](#schema_state) object for a valid identifiers. If the state does not exist, it creates a new state.



# createUser
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatusers

/runtime-openapi.json post /v1/chat/users
Creates a new [User](#schema_user). When creating a new [User](#schema_user), the required tags must be provided. See the specific integration for more details.



# getOrCreateUser
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/post-v1chatusersget-or-create

/runtime-openapi.json post /v1/chat/users/get-or-create
Retrieves the [User](#schema_user) object for given discriminating tags. If the user does not exist, it will be created. If the user already exists, its name, pictureUrl, attributes, and tags will be updated with the provided values.



# updateConversation
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/put-v1chatconversations

/runtime-openapi.json put /v1/chat/conversations/{id}
Update a [Conversation](#schema_conversation) object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.



# updateMessage
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/put-v1chatmessages

/runtime-openapi.json put /v1/chat/messages/{id}
Updates a message tags and payload. The message type cannot be changed. Calling this operation from an integration, to update an incoming message, will not invoke the bot. The other way around it also true; Calling this operation from the bot, to update an outgoing message, will not invoke the integration.



# updateUser
Source: https://botpress.com/docs/api-reference/runtime-api/openapi/endpoints/put-v1chatusers

/runtime-openapi.json put /v1/chat/users/{id}
Update a [User](#schema_user) object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.



# Getting Started
Source: https://botpress.com/docs/api-reference/tables-api/getting-started



The Tables API allows you to manage your tables, which store structured data and offer various features. You can use tables to store user data, automatically label data, and extract information from content.

All the endpoints of the Tables API are located behind the `tables` base path (`api.botpress.cloud/v1/tables/`).

## Using cURL

Calling the Tables API can be done using any HTTP client, such as `curl`, `axios`, or `fetch`. Here's an example using `curl`:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
token="$YOUR_BOTPRESS_TOKEN"
bot_id="$YOUR_BOT_ID"
## List your bot's tables
curl -H "Authorization: bearer $token" -H "x-bot-id: $bot_id" https://api.botpress.cloud/v1/tables
```

## Using the Official TypeScript Client

The official TypeScript client is available as an NPM package. You can install it using any of the following command:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install @botpress/client
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install @botpress/client
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add @botpress/client
  ```
</CodeGroup>

Once installed, you can import the client and use it in your TypeScript code:

<Note>
  This example uses [`dotenv` ](https://www.npmjs.com/package/dotenv) to manage Botpress credentials. If you'd rather manage your credentials differently, just remove the import and define your token and bot ID however you like.
</Note>

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

const main = async () => {
    const token = process.env.TOKEN
    const botId = process.env.BOT_ID

    const client = new Client({
        token,
        botId,
    })

    const response = await client.listTables({})
    console.log(response.tables)
}

void main()
```

## Quotas/limits

The maximum payload size for the Tables API is .


# deleteTable
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/delete-v1tables

/tables-openapi.json delete /v1/tables/{table}
Permanently deletes a table and all its associated data from the system. Use with caution, as this action cannot be undone.



# listTables
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/get-v1tables

/tables-openapi.json get /v1/tables
Retrieves a list of all tables associated with your bot.



# getTable
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/get-v1tables-1

/tables-openapi.json get /v1/tables/{table}
Retrieves detailed information about a specific table, identified by its name or unique identifier.



# getTableRow
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/get-v1tables-row

/tables-openapi.json get /v1/tables/{table}/row
Fetches a specific row from a table using the row's unique identifier.



# createTable
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables

/tables-openapi.json post /v1/tables
Initiates the creation of a new table based on the provided schema, excluding system-managed fields like IDs and timestamps.



# getOrCreateTable
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables-1

/tables-openapi.json post /v1/tables/{table}
Retrieves information about a specific table if it exists; otherwise, creates a new table based on the provided schema.



# duplicateTable
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables-duplicate

/tables-openapi.json post /v1/tables/{sourceTableId}/duplicate
Duplicates the table schema & content



# createTableRows
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables-rows

/tables-openapi.json post /v1/tables/{table}/rows
Inserts one or multiple new rows into the specified table.



# deleteTableRows
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables-rowsdelete

/tables-openapi.json post /v1/tables/{table}/rows/delete
Allows selective deletion of rows or complete clearance of a table.



# findTableRows
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables-rowsfind

/tables-openapi.json post /v1/tables/{table}/rows/find
Enables the search and filtering of rows within a table based on specific criteria. This operation supports complex queries for advanced data manipulation and retrieval.



# upsertTableRows
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/post-v1tables-rowsupsert

/tables-openapi.json post /v1/tables/{table}/rows/upsert
Inserts or updates rows based on a key. If a row exists, it is updated; otherwise, a new row is created.



# updateTable
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/put-v1tables

/tables-openapi.json put /v1/tables/{table}
Updates the schema or the name of an existing table.



# renameTableColumn
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/put-v1tables-column

/tables-openapi.json put /v1/tables/{table}/column
Renames an existing column within a table to better reflect its content or usage. The operation targets a specific table and requires the current and new column names.



# updateTableRows
Source: https://botpress.com/docs/api-reference/tables-api/openapi/endpoints/put-v1tables-rows

/tables-openapi.json put /v1/tables/{table}/rows
Updates specified rows in a table, allowing partial success with detailed feedback on errors.



# Changelog
Source: https://botpress.com/docs/changelog

The latest updates and improvements to Botpress.

<Update label="May 8, 2026">
  ## Features & enhancements

  * Improve UI for filtering conversations by message count

  ## Bug fixes

  * Fixed an issue where bots could fail to load on flaky networks (VPNs, proxies) due to dropped WebSocket connections
  * Reduced typing lag in the Autonomous Node transition condition input field
  * Fixed an issue where expired session tokens could prevent bots from reconnecting
  * Fixed an issue where closed conversations in the Human Handoff dashboard were not loading

  ## Integrations

  * **Odoo:** Added Odoo integration
  * **WhatsApp:** Added native support for Carousels and Cards
</Update>

<Update label="May 1, 2026">
  ## Features & enhancements

  * Added support for [Claude Opus 4.7](https://www.anthropic.com/news/claude-opus-4-7)
  * Added an integration hub to the dashboard:

  <Frame>
    <img alt="Integrations hub on the dashboard" />

    <img alt="Integrations hub on the dashboard" />
  </Frame>

  * Added a range slider for filtering conversations by number of messages in the [conversations menu](/docs/get-started/manage-your-agent/monitor#conversations):

  <Frame>
    <img alt="Conversation range slider" />

    <img alt="Conversation range slider" />
  </Frame>

  ## Bug fixes

  * Fixed an issue where Nodes could become corrupted or inconsistent when using multiplayer in Studio
  * Fixed an issue where multiplayer was causing some users to get stuck on the “Loading bot” screen or would receive a “Failed to load bot” error
  * Fixed an issue where formatting problems were adding unnecessary latency to the Translator Agent’s JSON response
  * Fixed an issue where the AI Generate Text Card was displaying an incorrect token limit under the **Prompt** field for certain models
  * Fixed an issue where refreshing the page after saving the Human-in-the-Loop (HITL) integration’s configuration would erase the values of the configuration fields
  * Fixed an issue where the Webchat delivery status indicator wasn’t translated to languages other than English

  ## Integrations

  * **Slack**: Video and audio messages now appear as native media in Slack instead of plain text links
  * **Linear**: Webhooks for issues and comments now register automatically when you connect your account
  * **Airtable**: Added option to connect via OAuth
</Update>

<Update label="April 24, 2026">
  ## Features & enhancements

  * Added auto-translation for Webchat UI components based on browser locale

  ## Bug fixes

  * Fixed an issue where the initial bot setup would get stuck on a loading screen without completing or timing out
  * Fixed a visual issue in the pricing plan selection dialog
  * Fixed various issues with the integration hub
  * Fixed an issue where Webchat conversation history would persist indefinitely even when configured to clear data when the browser tab closes
  * Fixed an issue where the Human-in-the-Loop dashboard was reloading the entire conversation list every few seconds, causing unnecessary slowdowns

  ## Integrations

  * **Postmark**: Added Postmark integration
  * **Messenger and Facebook**: Fixed an error during OAuth setup where fetching Facebook Pages could fail due to incorrect API response parsing
  * **Slack**: Improved manual configuration process using OAuth
  * **Zendesk Messaging HITL**: Added support for linking sessions to existing Zendesk Support users by passing a user's `externalId` into the Email field
    on the Start HITL card.
  * **HubSpot**: Added support for Human-in-the-Loop (HITL)
</Update>

<Update label="April 17, 2026">
  ## Revamped Autonomous Node

  Improved the UX of the Autonomous Node, including a brand new prompt editor which:

  * Provides a macro menu for quickly referencing Knowledge Base, variables and more
  * Introduces a raw Markdown mode for precise editing

  <Tabs>
    <Tab title="Autonomous Node">
      <Frame>
        <img alt="Autonomous Node" />

        <img alt="Autonomous Node" />
      </Frame>
    </Tab>

    <Tab title="Prompt editor">
      <Frame>
        <img alt="Prompt editor" />

        <img alt="Prompt editor" />
      </Frame>
    </Tab>
  </Tabs>

  ## Improved Studio multiplayer

  Revamped the Studio multiplayer and added multiple features/enhancements, including:

  * Greatly improved performance and latency
  * Real-time cursor position display for teammates
  * Ability to "focus" on a specific teammate and follow their cursor
  * Visual indicators displaying which Node each teammate is focused on

  ## Bug fixes

  * Fixed a race condition which was preventing bots from responding when opening the Webchat preview URL under certain circumstances

  ## Integrations

  * **Telegram**: Fixed an issue where the typing indicator was raising errors when the typing indicator emoji was disabled
  * **WhatsApp**: Fixed an issue where events sent by WhatsApp were mistakenly raising an error
</Update>

<Update label="April 10, 2026">
  ## Redesigned integrations Hub

  Revamped the design of the integration Hub:

  <Frame>
    <img alt="Integrations Hub" />

    <img alt="Integrations Hub" />
  </Frame>

  ## New knowledge source providers

  Added new knowledge source providers to Knowledge Bases:

  * Linear
  * GitHub
  * Confluence
  * Google Drive
  * Notion

  <Frame>
    <img alt="New knowledge sources" />

    <img alt="New knowledge sources" />
  </Frame>

  ## Integrations

  * **Discord**: Added [Discord](/docs/integrations/integration-guides/discord) integration
  * **Zoom**: Added a new Transcript Received Trigger that returns the raw content of a meeting's transcript

  ## Bug fixes

  * Fixed an issue with editing two bots simultaneously in different browser tabs where saving one bot would corrupt the draft of the other
  * Fixed an issue in the [Human Handoff](/docs/get-started/manage-your-agent/human-handoff) dashboard where long messages would overflow horizontally
</Update>

<Update label="April 3, 2026">
  ## Studio

  ### Features & enhancements

  * Added option to select the model used by the Vision Agent inside [Extract Content from Image](/docs/studio/concepts/agents/vision-agent#extract-from-incoming-images) Card
  * Added `--url` flag to CLI `deploy` command allowing you to pass a custom URL when deploying an integration

  ### Integrations

  * **Airtable**: Improved UX of adding Fields in Cards.
  * **Slack**:
    * Improved use of mentions in broadcast messages
    * Added [Get Channels Info](/docs/integrations/integration-guides/slack#get-channels-info) action
  * **WhatsApp**:
    * Added configuration option for customizing typing indicator
    * Added support for using named parameters in template variables
  * **Google Sheets**: Improved OAuth configuration flow
  * **Salesforce**: Improved OAuth configuration flow
  * **Kommo**: Added Kommo Integration

  ### Bug fixes

  * Fixed issues in Tables with columns duplicating or disappearing when being renamed
</Update>

<Update label="March 27, 2026">
  ## Studio

  ### Features & enhancements

  * New AI Models: Claude Opus 4.5, Qwen3 8B, Gemini 2.5 Pro/Flash-Lite, Gemini 3.1 Pro/Flash-Lite, Grok 4.1 Fast, Grok 4.20
  * Added support for bot secrets in SDK

  ### Integrations

  * **Dropbox**: You can now sync files to Knowledge Bases
  * **WhatsApp**: Added [List Message Templates](/docs/integrations/integration-guides/whatsapp/introduction#list-message-templates) Card
  * **Linear**: Added new Triggers:
    * [Aggregate File Changes](/docs/integrations/integration-guides/linear#aggregate-file-changes)
    * [File Created](/docs/integrations/integration-guides/linear#file-created)
    * [File Deleted](/docs/integrations/integration-guides/linear#file-deleted)
    * [File Updated](/docs/integrations/integration-guides/linear#file-updated)
    * [Folder Deleted Recursive](/docs/integrations/integration-guides/linear#folder-deleted-recursive)
  * **GitHub**: Added new Triggers:
    * [Aggregate File Changes](/docs/integrations/integration-guides/github#aggregate-file-changes)
    * [File Created](/docs/integrations/integration-guides/github#file-created)
    * [File Deleted](/docs/integrations/integration-guides/github#file-deleted)
    * [File Updated](/docs/integrations/integration-guides/github#file-updated)
    * [Folder Deleted Recursive](/docs/integrations/integration-guides/github#folder-deleted-recursive)
  * **Telegram**: Added typing indicator toggle in integration settings

  ### Bug fixes

  * Fixed an issue with conversations appearing empty when [AI insights](/docs/get-started/manage-your-agent/monitor#ai-insights) were disabled

  ***

  ## ADK

  ### Control Panel

  * Added a global command palette (`Cmd+K` / `Ctrl+K`) for quick navigation in the Control Panel
  * New **Models** page listing all available models
  * Updated UI for **Settings** and **Trigger** pages
  * Added Agent Steps to **Chat** page to see what your agent is doing while it runs
  * **Actions page** accepts JSON5/JS object syntax for testing actions

  ### CLI

  * Added `adk models` command to see all available models
</Update>

<Update label="March 20, 2026">
  ## Studio

  ### Features & enhancements

  * New AI Models: GPT 5.4, Sonnet 4.6, Opus 4.6, Gemini 3.1 Pro Preview
  * Added support for MDX (Markdown JSX) in the Files API

  ### Integrations

  * All integrations now automatically save configuration settings upon completion of OAuth
  * **Linear**, **HubSpot**, **LinkedIn**, **GitHub**, and **Notion** now supports OAuth for multiple bots
  * **WeChat**: Added WeChat integration
  * **WhatsApp**: Added events to track outbound message delivery lifecycle

  ### Bug fixes

  * Fixed issue where integration settings were reset on update
  * Fixed issue with duplicate header names in Tables
  * Fixed issue with duplicate variables being created after variable deletion
  * Fixed errors when connecting additional stylesheets in Webchat

  ***

  ## ADK

  ### Control Panel

  * Added Copilot (OpenCode) Panel

  <Frame>
    <img alt="ADK Control Panel with Copilot (OpenCode)" />

    <img alt="ADK Control Panel with Copilot (OpenCode)" />
  </Frame>

  * Added Chat history in Conversations page
  * Updated Traces page UI

  ### CLI

  * Self upgrade support for Windows using `adk self-upgrade`
  * Add Copilot (OpenCode) support using `adk dev --copilot`
</Update>

<Update label="March 13, 2026">
  ## Studio

  ### Features & enhancements

  * Webchat can now recover messages if user's connection is interrupted

  ### Integrations

  * **Zendesk**: Improved HITL support
  * **HITL**: Added support to pass additional information through tags
  * **Google Calendar** and **Google Sheets**: OAuth is now available

  ### Bug fixes

  * Fixed an issue where Bot Identity and Styling changes were not saving
  * Fixed an issue where default boolean columns in the **Insert Record** card did not default to false
  * Fixed an issue in Webchat where text messages appeared as code blocks

  ***

  ## ADK

  ### Control Panel

  * Added a visual Chat view to test conversations and traces (requires Webchat installation):

  <Frame>
    <img alt="Chat view with Timeline and Bot conversation" />

    <img alt="Chat view with Timeline and Bot conversation" />
  </Frame>

  * Updated the UI for the **Tables** and **Traces** pages
  * Added variable validation for **Configuration Variables**
  * Improved the type system for workflow events in conversation handlers

  ### CLI

  * Improved support for Windows
  * MCP port can now be assigned using `adk mcp --port <port>`
  * The Control Panel no longer opens automatically on `adk dev`
</Update>

<Update label="March 6, 2026">
  ## Studio

  ### Features & enhancements

  * Improved breakdown UI for **AI Spend by Source** dashboard
  * Improved logging for Integrations in **Audits** page

  ### Integrations

  * **Dropbox**: Added OAuth configuration
  * **HubSpot**: Added new cards
    * [Get Company](/docs/integrations/integration-guides/hubspot#get-company)
    * [Update Company](/docs/integrations/integration-guides/hubspot#update-company)

  ***

  ## ADK

  ### Control Panel

  * The dev console has been replaced by the **Control Panel**
  * Dark (default) and light themes with toggle in the top bar
  * New **Overview** page with panels for Agent summary, Component inventory, and Runtime and Integrations:

  <Frame>
    <img alt="ADK Control Panel with sidebar and main view" />

    <img alt="ADK Control Panel with sidebar and main view" />
  </Frame>

  * Restructured sidebar into **Connect**, **Build**, **Data**, and **Observe** sections
  * Improved UI across **Workflow**, **Logs** and **Traces** pages
  * Added ability to test Integration and Bot Actions in one place on the **Actions** page:

  <Frame>
    <img alt="Actions page with Integration and Bot Actions" />

    <img alt="Actions page with Integration and Bot Actions" />
  </Frame>

  * Added a **Triggers** page for managing triggers in your ADK agents:

  <Frame>
    <img alt="Triggers page in Control Panel" />

    <img alt="Triggers page in Control Panel" />
  </Frame>

  * Added an **Evals** page for running declarative conversation tests on your ADK agents:

  <Frame>
    <img alt="Evals page for declarative conversation tests" />

    <img alt="Evals page for declarative conversation tests" />
  </Frame>

  * Added Configuration Variable management in the **Settings** page:

  <Frame>
    <img alt="Configuration Variable management in Settings" />

    <img alt="Configuration Variable management in Settings" />
  </Frame>

  * Testing page removed

  ### CLI

  * Added support to create a new agent without prompts by use `adk init --yes` or `adk init --defaults`
  * Use `adk init --skip-link` to skip the interactive bot-linking step
  * You can set the Control Panel theme (dark or light) using `adk theme`
</Update>

<Update label="February 27th, 2026">
  ## Features & enhancements

  * Added a new onboarding experience when creating a bot in Studio:

  <Frame>
    <img alt="Choose an option - Guided Setup or Start from Scratch" />

    <img alt="Choose an option - Guided Setup or Start from Scratch" />
  </Frame>

  * Improved formatting for lists and headings in [Comment Cards](/docs/studio/concepts/cards/utilities#comment)

  ## Bug fixes

  * Fixed an issue where the **Unsaved changes** button appeared even after saving
  * Fixed an issue where inserting Cards into a Node caused them to appear in previously selected Nodes
  * Fixed an issue where variables were unintentionally removed from an Autonomous Node while editing instructions
  * Fixed an issue where non-nullable table fields were incorrectly defaulting to null
</Update>

<Update label="February 20th, 2026">
  ## Features & enhancements

  * Improved response for retry on [Capture Information Cards](studio/concepts/cards/capture-information)
  * Improved autoscroll behaviour of new messages in Webchat

  ## Bug fixes

  * “Select All” in Knowledge Base now accurately selects visible (filtered) documents and data sources
</Update>

<Update label="February 13th, 2026">
  ## Features & enhancements

  * Improved error handling for AI Code Suggestions in [Execute Code Cards](/docs/studio/concepts/cards/execute-code)
  * Improved website crawling for Knowledge Bases
  * Added support for variables in Confirm Cancel Messages in [Single Choice Cards](studio/concepts/cards/capture-information#single-choice)
  * Improved UI for dark mode in Webchat

  ## Integrations

  * **Sunshine Conversations**: Added OAuth configuration

  ## Bug fixes

  * Fixed an issue of generating multiple ports
  * Prevent crashing on certain search terms
</Update>

<Update label="February 6th, 2026">
  ## Features & enhancements

  * Added the option to show/hide empty conversations in the dashboard:

  <Frame>
    <img alt="Show empty conversations" />

    <img alt="Show empty conversations" />
  </Frame>

  * Improved UX for inserting a link in a comment Node
  * Improved the Translation Agent's performance when translating dropdown and multiple choice messages

  ## Integrations

  * **LinkedIn**: Added LinkedIn integration
  * **WhatsApp**: Fixed an issue where the message delivery status wasn’t updating properly in playground
  * **Trello**: Improved security and reliability

  ## Bug fixes

  * Fixed an issue where Actions would fail to capture input on first attempt
  * Fixed Knowledge Bases being deleted right after creation in new bots under certain circumstances
</Update>

<Update label="January 30, 2026">
  ## Features & enhancements

  * [Gemini 3 previews](https://aistudio.google.com/models/gemini-3) are now available in Studio
  * Improved UI for viewing video guides in Studio
  * You can now copy the raw LLMz output when inspecting a message in the emulator
  * Studio now displays exactly which configuration field is causing an error when attempting to save an integration's configuration
  * Added support for BCP 47 to the Translator Agent, which helps distinguish between traditional and simplified Chinese

  ## Integrations

  * **BambooHR**: Fixed an issue that was causing the [Get Custom Info](/docs/integrations/integration-guides/bamboohr#get-custom-info) Card to not return any fields
  * **WhatsApp**:
    * Improved logging when messages fail to send
    * Added referral metadata to tags, which provides details about the origin of the conversation

  ## Bug fixes

  * Fixed an issue where changes to a Workflow were being lost due to a failure to save the Workflow
  * Fixed an issue where certain integrations showed an error message before attempting to save the configuration
  * Fixed an issue where certain Knowledge Base IDs were being duplicated when copying a bot
  * Fixed an issue where the [Find Records](/docs/studio/concepts/cards/tables#find-records) Card wasn't working properly with queries containing variables
  * Fixed a visual issue with the error message displayed when attempting to drag Autonomous Node Cards into a Standard Node
  * Fixed a visual issue where default connectors were missing from Nodes with multiple exit connectors
  * Fixed an issue where hooks related to an integration were deleted after copying a bot if that integration wasn't enabled or configured
  * Fixed an issue where large favicons were preventing websites from being crawled properly
</Update>

<Update label="January 23, 2026">
  ## Additional context for Agents

  When using the Translator Agent or Summary Agent, you can now provide additional context via an **Additional Context** field:

  <Frame>
    <img alt="Additional context" />

    <img alt="Additional context" />
  </Frame>

  ## Logging options

  You can now configure a **Logging Mode** in your bot's settings:

  <Frame>
    <img alt="Logging mode" />

    <img alt="Logging mode" />
  </Frame>

  This lets you choose between 4 options for logging:

  * **Enabled**: Displays all logs
  * **Verbose**: Displays all logs with as much detail as possible
  * **Disabled**: Doesn't display any logs
  * **Console logs only**: Only displays logs you've written yourself

  ## Integrations

  * **Tally**: Added Tally integration
  * **Slack**:
    * Added **Reply Behaviour** field to configure where the bot should send replies (in the channel, thread, or both)
    * Added parsing from Markdown to [`mrkdwn`](https://docs.slack.dev/messaging/formatting-message-text/#basic-formatting)
  * **Twilio**:
    * Added typing and "read" indicator support
    * Improved rendering for multiple content types in the same message
  * **Zendesk**: Improved logging and error tracking
  * **Trello**: Various bug fixes and improvements

  ## Bug fixes

  * Fixed an issue that was preventing horizontal scrolling in Tables and Knowledge Bases
  * Fixed an issue where adding the same website page to 2 different Knowledge Bases would cause the first Knowledge Base to delete that page
  * Fixed an issue where website Knowledge Base sources were reappearing after being deleted
  * Fixed an issue where conversation variables and user variables didn't persist their assigned value after the conversation transitioned to another Workflow
  * Fixed an issue where using Anthropic models with the Personality Agent was causing unexpected errors
  * Fixed an issue where copying a bot to a new bot didn't enable integrations automatically
  * Fixed an issue where Start Nodes could be copied, even if the copies never executed
  * Fixed an issue where additional End Nodes couldn't be deleted when created as copies of the default End Node
  * Fixed an issue with the Summary Agent where setting the **Transcript Max Messages** setting to 0 would cause an error
  * Fixed an issue with integration pages in the Hub where the Card schemas displayed matched the latest version of the integration instead of the currently installed version
  * Fixed an issue where the Capture Information Card's **Skip if variable is already filled** option wasn't skipping properly when the assigned value was an empty object
</Update>

<Update label="January 16, 2026">
  ## Features & enhancements

  * You can now use models from [Mistral AI](https://mistral.ai/) by installing the official integration
  * Users can now upload `.gif` and `.webp` images to their conversations in Webchat
  * When users upload a file to a Webchat conversation, the Botpress file ID is now included in the event's payload as `fileId`. This allows the bot to manipulate the uploaded file directly (for example, changing its permissions or deleting it)

  ***

  ## Integrations

  ### BambooHR

  Improved parsing for input in the integration's configuration fields

  ### Gmail

  * Improved error handling for when users delete messages
  * Fixed bug that was causing messages to be processed multiple times

  ### Google Sheets

  Added new Cards:

  * [Find Rows](integrations/integration-guides/gsheets#find-rows)
  * [Find Row (First Match)](integrations/integration-guides/gsheets#find-row-first-match)
  * [Get Row](integrations/integration-guides/gsheets#get-row)
  * [Update Row](integrations/integration-guides/gsheets#update-row)
  * [Insert Row at Index](integrations/integration-guides/gsheets#insert-row-at-index)
  * [Delete Rows](integrations/integration-guides/gsheets#delete-rows)
  * [Upsert Row](integrations/integration-guides/gsheets#upsert-row)

  ### Intercom HITL

  * The conversation title in Botpress is now sent to Intercom when escalating a conversation

  ### Linear

  * **Get User** Card can now get the currently authenticated user
  * The **List Teams** Card's output now includes each team’s unique key

  ### Notion

  * Added new Cards:

    * [Get Page](integrations/integration-guides/notion#get-page)
    * [Search by Title](integrations/integration-guides/notion#search-by-title)
    * [Get Page Content](integrations/integration-guides/notion#get-page-content)
    * [Append Blocks to Page](integrations/integration-guides/notion#append-blocks-to-page)
    * [Update Page Properties](integrations/integration-guides/notion#update-page-properties)

  * Added a new Trigger:
    * [Comment Created](integrations/integration-guides/notion#comment-created)

  ### Zoom

  * When a Zoom transcript is completed, the **Transcript Received** Trigger now includes the audio URL in the transcript

  ***

  ## Bug fixes

  * Fixed an issue where the Summary Agent's transcript message was not returning the entire transcript history
  * Fixed a visual bug where Workflow context menu was being duplicated when opened over the Card tray
  * Fixed an issue with the emulator where tools didn’t work properly when added to the same Autonomous Node multiple times
  * Fixed an issue where the Studio would get stuck on the loading screen if the browser window was out of focus
  * Fixed the **Watch Video** button for individual Cards in the Card tray
  * Fixed the Translator Agent's prompt to better support dropdowns
  * Fixed issues with multiplayer in the Studio where recent changes were lost if the connection was unstable
  * Fixed an issue where **Reset bot to default** wasn't deleting Knowledge Bases
  * Fixed a visual issue where an error screen was flashing when creating a new bot
  * Fixed an issue where the user's configuration for Webchat's embedded chat ID / toggle chat ID was mistakenly being overwritten
</Update>

<Update label="January 9, 2026">
  ## Dashboard displays bot creator

  The dashboard now displays which member of your workspace created a bot:

  <Frame>
    <img alt="Bot creator" />

    <img alt="Bot creator" />
  </Frame>

  ## Integrations

  * **Hub**: Botpress Hub now has callouts clearly showing when an integration version is deprecated
  * **Chatwoot**: [Added Chatwoot integration](/docs/integrations/integration-guides/chatwoot)
  * **Slack**: Fixed an issue where messages containing percentage symbols were causing errors
  * **Sunshine Conversations**: Added `origin` conversation tag for tracking what channel a conversation originated from
  * **Zendesk**: Added information about the requester when creating a ticket in Zendesk from the Start HITL Card

  ## Bug fixes

  * Fixed an issue where Autonomous Node responses were incorrectly exceeding the maximum payload size
  * Fixed visual issues with CLI authentication
  * Fixed a visual bug with scrolling to the **Copy to bot** option in the Dashboard
  * Fixed an issue where user data wasn't properly persisted when injecting Webchat
</Update>

<Update label="December 19, 2025">
  ## Create ADK agents from the dashboard

  * Added support for creating an ADK agent from the dashboard:

  <Frame>
    <img alt="ADK flow" />
  </Frame>

  ## GPT-5.2

  * Added support for GPT-5.2 from OpenAI

  ## Integrations

  * **Gmail**: Added [Cards](/docs/integrations/integration-guides/gmail#cards) to the Gmail integration
  * **Zendesk**: Added OAuth configuration
  * **Messenger & Facebook**: Added [Start DM Conversation from Comment](integrations/integration-guides/messenger#start-dm-conversation-from-comment) Card
</Update>

<Update label="December 12, 2025">
  ## Webchat input improvements

  * Starting with Webchat 3.5, Webchat input is disabled while your bot processes a message

  ## Integrations

  * **Sunshine Conversations**: Added support for incoming files

  ## Bug fixes

  * Fixed an issue where deleting a comment Node would sometimes delete nearby transitions
</Update>

<Update label="December 5, 2025">
  ## Dashboard improvements

  * Added menu to manage website Knowledge Base crawling
  * Improved UX for filtering conversations:

  <Frame>
    <img alt="Conversation filters" />

    <img alt="Conversation filters" />
  </Frame>

  ## Integrations

  * **Linear**: Fixed an issue where bots would reply to their own comments in an endless loop
  * **Notion**: Improved error handling

  ## Bug fixes

  * Fixed an issue where code editors in the Studio became unresponsive after switching to new tab
  * Fixed and issue where leaving the optional subtitle field empty in Carousel Cards would result in an error
</Update>

<Update label="November 28, 2025">
  ## Features & enhancements

  * Improved UI for the model picker in the Studio:

  <Frame>
    <img alt="New model picker" />

    <img alt="New model picker" />
  </Frame>

  * Added option to automatically recharge your bot's add-ons using **Auto-Recharge**

  ## Integrations

  * **WhatsApp**:
    * Added support for captions in images
    * Improved handling for long messages (4096+ characters)
  * **Messenger**: Improved error handling
  * **Intercom**: Fixed images and text being sent out of order
  * **Email notifier**: Added support for line breaks

  ## Bug fixes

  * Fixed a visual issue with file upload in the Emulator
  * Fixed an issue where Knowledge Base entries were disappearing after indexing under certain circumstances
  * Fixed an issue where variables were being overwritten when opening Bot Settings.
  * Fixed an issue where toggling the bottom pane was not working
</Update>

<Update label="November 21, 2025">
  ## Features & enhancements

  * Improved performance across the Studio
  * Improved rendering of bullets and lists in the Emulator
  * Improved error handling for **Copy to bot** feature
  * Improved error messaging when limit usage is reached in Dashboard

  ## Integrations

  * **Messenger**: Added support for interaction with Facebook pages, including comment replies and private conversations started from Facebook comments
  * **Email Notifier**: Added option to specify a reply-to email address in the [Send Mail](/docs/integrations/integration-guides/plus-email-notifier#send-email) Card

  ## Bug fixes

  * Fixed an issue where the Translator Agent was ignoring model preference set in global bot configuration
  * Fixed an issue where Knowledge Bases in the Studio homepage weren’t displaying updated data
  * Fixed an issue with variable capture in the Conversation End Workflow where Capture Information Cards appeared to succeed but weren't actually storing variables
  * Fixed an issue with copy-paste operations in text editors where keyboard shortcuts (<kbd>Cmd+A</kbd>, <kbd>Cmd+C</kbd>, <kbd>Cmd+V</kbd>) were copying JSON instead of the selected text
  * Fixed sidebar visual bug in Webchat configuration
  * Fixed visual issue with dark mode on Firefox and Safari
  * Fixed visual issues with Webchat components and styles
</Update>

<Update label="November 14, 2025">
  ## Features & enhancements

  ### GPT-5.1 support

  * Added support for GPT-5.1 from OpenAI

  ### Webchat 3.4

  * Released Webchat 3.4. Improvements include:
    * Added the ability to paste images from clipboard
    * Improved scrolling smoothness
    * Improved typing indicators
    * Improved media rendering
    * Improved performance and reliability

  ### Dashboard

  * Redesigned Webchat configuration split into four sections:

  <Tabs>
    <Tab title="Bot Identity">
      <Frame>
        <img alt="Bot Identity" />

        <img alt="Bot Identity" />
      </Frame>
    </Tab>

    <Tab title="Bot Appearance">
      <Frame>
        <img alt="Bot Appearance" />

        <img alt="Bot Appearance" />
      </Frame>
    </Tab>

    <Tab title="Deploy Settings">
      <Frame>
        <img alt="Deploy Settings" />

        <img alt="Deploy Settings" />
      </Frame>
    </Tab>

    <Tab title="Features">
      <Frame>
        <img alt="Features" />

        <img alt="Features" />
      </Frame>
    </Tab>
  </Tabs>

  * Added keyboard shortcuts to Workspace selector

  ## Card tray

  * Redesigned the Card tray as a modal:

    <Frame>
      <img alt="Card tray" />

      <img alt="Card tray" />
    </Frame>

  ## Integrations

  * **Hunter**: Added [Hunter](/docs/integrations/integration-guides/hunter) integration
  * **Slack**: Added ability for bot to retrieve a private channel
  * **WhatsApp**: Fixed an issue where messages were being duplicated under certain circumstances
  * **HubSpot**: Improved error logging when pipeline status can't be found

  ## Bug fixes

  * Fixed an issue where searching in Studio was not working under certain circumstances
  * Fixed an issue where hotkeys weren’t working properly when tables were open
  * Fixed an issue with Human Handoff where typing indicator showed even when the support agent wasn't typing
  * Fixed a visual issue with Knowledge Bases in the Dashboard in dark mode
  * Fixed an issue where log filters weren’t updating the displayed logs correctly
</Update>

<Update label="November 7, 2025">
  ## Features & enhancements

  * Redesigned billing section in the Dashboard:

  <Frame>
    <img alt="New billing section" />

    <img alt="New billing section" />
  </Frame>

  * Added option to rename [Execute Code Cards](/docs/studio/concepts/cards/execute-code)
  * Added handling to allow adding duplicate files to Webchat message
  * Added option to configure custom analytics for an entire workspace

  ## Integrations

  * **HubSpot**: Added [Search Company](/docs/integrations/integration-guides/hubspot#search-company) Card
  * **Workable**: Added [Get Job Questions](/docs/integrations/integration-guides/workable#get-job-questions) Card
  * **Intercom HITL**: Improved handling for email address formatting
  * **Sharepoint**: Fixed an issue with syncing document libraries on registration

  ## Bug fixes

  * Fixed an issue with the [AI Transition](/docs/studio/concepts/cards/ai/ai-transition) Card where newly-added fields would be impossible to delete
  * Fixed an issue where the [Capture Information](/docs/studio/concepts/cards/capture-information) Card's **Skip if variable is already filled** option wasn't working    properly
  * Fixed issue where the Dashboard's hotkeys were interfering with the Help Desk bot
  * Fixed visual issues with viewing Knowledge Bases on mobile Dashboard
  * Fixed a visual issue where Webchat bot contact info was being displayed even when configuration fields were empty

  ## Miscellaneous

  * Added two new methods returned by the Webchat React library's [`useWebchat`](/docs/webchat/react-library/hooks/use-webchat-client) hook: `bindConversation` and `bindUser`
</Update>

<Update label="October 31, 2025">
  ## Features & enhancements

  ### New Actions experience

  Overhauled the Actions experience and added ability generate Actions and Schemas using AI:

  <Tabs>
    <Tab title="Just write your prompt...">
      <Frame>
        <img alt="Action prompt" />

        <img alt="Action prompt" />
      </Frame>
    </Tab>

    <Tab title="then use the generated Action.">
      <Frame>
        <img alt="Generated action" />

        <img alt="Actions" />
      </Frame>
    </Tab>
  </Tabs>

  ### Dashboard improvements

  * Added the ability to manage Knowledge Bases from the Dashboard:

  <Frame>
    <img alt="Dashboard Knowledge Bases" />

    <img alt="Dashboard Knowledge Bases" />
  </Frame>

  * Redesigned agent overview page with better metrics, feature visibility, and a link to the bot's shareable preview:

  <Frame>
    <img alt="New agent overview" />

    <img alt="New agent overview" />
  </Frame>

  * Redesigned Conversations tab that shows you Conversation Insights, sentiment analysis and an AI summary:

  <Frame>
    <img alt="New Conversations tab" />

    <img alt="New Conversations tab" />
  </Frame>

  ## Integrations

  * **Workable**: Added [Workable](/docs/integrations/integration-guides/workable) integration
  * **Mintlify**: Added [Mintlify](/docs/integrations/integration-guides/mintlify) integration
  * **WhatsApp**: Fixed an issue with parsing Mexican phone numbers
  * **Freshchat**: Fixed an issue with handling empty events
  * **HubSpot**: Fixed an issue where Cards that return search results would cause errors when no results were found
  * **Instagram**: Added option for bot to reply to comments on posts
  * **Twilio**:
    * Added new Cards: **Start Conversation** and **Get or Create User**
    * Added better Markdown support

  ## Bug fixes

  * Fixed visual bug when loading variable picker in a Card's inspector
  * Fixed a bug where user variables would reset with each new conversation in the Emulator
  * Fixed an issue where sending multiple API requests to upsert rows using the Tables API was causing duplicate rows

  ## Miscellaneous

  * Added file metadata to the [`searchFiles`](/docs/api-reference/files-api/openapi/searchFiles) endpoint's response
</Update>

<Update label="October 24, 2025">
  ## Integrations

  * **BambooHR**: Added BambooHR integration
  * **Instagram**: Added option for bot to reply to comments on posts
  * **Airtable**: Improved error logging when Cards fail

  ## Bug fixes

  * Fixed an issue where loading multiple documents into a Knowledge Base would stall if the Knowledge Base also contained many website pages
  * Fixed visual bug with pagination in Knowledge Base documents

  ## Miscellaneous

  * Retired integrations are now listed as deprecated in Studio, preventing installation
</Update>

<Update label="October 17, 2025">
  ## Features & enhancements

  * Improved the UI for the Studio's **Publish** button:

  <Frame>
    <img alt="Publish button" />

    <img alt="Publish button" />
  </Frame>

  * Added support for [Claude Haiku 4.5](https://www.anthropic.com/news/claude-haiku-4-5) via the Anthropic integration

  ## Bug fixes

  * Fixed an issue where clicking Tools in your bot's home screen would cause a crash if your bot only contained standard Nodes
  * Fixed an issue where duplicating a Workflow would incorrectly display "Integration not installed or disabled" even though the integration was installed
  * Fixed an issue where imported bots would display ghost Knowledge Bases
  * Fixed an issue where previously-created variables were unavailable to select in certain Cards' output
  * Fixed an issue where the `event` object's state was inaccessible in Actions
  * Fixed an issue where URLs with backslashes weren’t crawling properly
</Update>

<Update label="October 10, 2025">
  ## Bug fixes

  * Fixed an issue where the **Copy to bot** option wasn't displaying all available bots after a certain number
  * Fixed a bug with storing a Card's output in a variable, where:
    * Existing Workflow variables weren't visible in the output picker
    * Creating a variable within the picker resulted in a duplicate variable if it had the same name as an existing variable
  * Fixed an issue where the Set Activity Timeout Card wasn't working under certain circumstances
  * Fixed an issue that was making the Webchat typing indicator appear and disappear irregularly while a bot prepared its reply
  * Fixed an issue where file storage wasn't always being reduced even when file was deleted from bot

  ## Features & enhancements

  * Conversations with the Botpress Help Desk now persist between the Dashboard and the Studio

  ## Integrations

  * **WhatsApp**: Added better support for international phone numbers
</Update>

<Update label="October 3, 2025">
  ## Features & enhancements

  ### Login

  * Refreshed [login page](https://sso.botpress.cloud/login):

  <Frame>
    <img alt="New login page" />
  </Frame>

  ### Onboarding

  * Improved onboarding experience:

    * Refreshed, more focused UI
    * Added option to describe your bot's goal when selecting **Other**:

  <Tabs>
    <Tab title="Select goal">
      <Frame>
        <img alt="Other use case" />

        <img alt="Other use case" />
      </Frame>
    </Tab>

    <Tab title="Describe goal">
      <Frame>
        <img alt="Goal" />

        <img alt="Goal" />
      </Frame>
    </Tab>
  </Tabs>

  * Tasks now run in the background while you're setting up your agent, making the onboarding experience much faster

  ### Studio

  * Added [Claude Sonnet 4.5](https://www.anthropic.com/news/claude-sonnet-4-5) to Studio

  ## Integrations

  * **Apify**: Added [Apify integration](/docs/integrations/integration-guides/plus-apify) for advanced website crawling
  * **WhatsApp**:
    * Added [new Triggers](integrations/integration-guides/whatsapp/introduction#triggers) to for monitoring [message templates](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/)
    * Fixed an issue where Freshchat agents' messages weren't being displayed on WhatsApp
  * **HubSpot**: Updated [Get Contact](/docs/integrations/integration-guides/hubspot#get-contact) Card to retrieve all contact properties by default

  ## Miscellaneous

  <Warning>
    ### Webchat v1 deprecation

    We're deprecating Webchat v1 (and any old implementations tied to it). This means
    any Webchat deployments on your website that use v1 will stop functioning. To avoid
    service disruption, all users currently using v1 must migrate to Webchat v2 or higher
    before **December 31, 2025**.

    If you're currently a Webchat v1 user, you should have already received an email with instructions for upgrading. For any questions, don't hesitate to contact our support team.
  </Warning>
</Update>

<Update label="September 26, 2025">
  ## Features & enhancements

  ### Webchat

  * Added the option to configure a [custom Webchat toggle](/docs/webchat/interact/use-custom-toggle):

  <Frame>
    <img alt="Custom Webchat toggle" />

    <img alt="Custom Webchat toggle" />
  </Frame>

  * Added the option to [inject Webchat into a specific HTML element](/docs/webchat/get-started/embed-in-element)
  * Added the option to enable sound effects for Webchat
  * Improved the Webchat customization UI

  ### Autonomous Nodes

  * Added the option to [set a specific LLM for Retrieval-Augmented Generation (RAG) tasks](/docs/studio/concepts/bot-settings#rag-language-model), like searching a Knowledge Base
  * Added the option to [override your bot's default LLM settings](/docs/studio/concepts/nodes/autonomous-node#override-default-models) at the Node level

  ### Studio

  * Added the option to select another bot when Studio is already open in another tab:

  <Frame>
    <img alt="Bot selector" />

    <img alt="Bot selector" />
  </Frame>

  ## Integrations

  * [Email Notifier](/docs/integrations/integration-guides/plus-email-notifier): Added an integration for sending emails from a generic email address
  * **Apollo**: Added [Apollo](/docs/integrations/integration-guides/apollo) integration
  * **Attio**: Added [Attio](https://attio.com/) integration
  * **Slack**: Added support for tagged Slack users in incoming message payloads

  ## Bug fixes

  * Fixed an issue where dynamically including Knowledge Bases in Autonomous Nodes (using a variable) wasn't working properly
  * Fixed an issue with the Slack integration where quick replies would result in a 400 error
</Update>

<Update label="September 19, 2025">
  ## Features & enhancements

  * Added option to rename rich text Knowledge Bases

  * Improved UI for array input fields in Cards

  * Added a safer check when deleting bots:

    <Frame>
      <img alt="Confirm delete" />

      <img alt="Confirm delete" />
    </Frame>

  * Added a search tab to workspace/bot selection dropdown

  ## Integrations

  * **Klaviyo**: Added [Klaviyo integration](/docs/integrations/integration-guides/klaviyo)
  * **Pipedrive**: Added [Pipedrive integration](/docs/integrations/integration-guides/pipedrive)
  * **MailerLite**: Added [MailerLite integration](/docs/integrations/integration-guides/mailerlite)
  * **Slack**: Added support for incoming Slack messages containing images, audio, files, and multiple files
  * **Loops**: Added attachment support to the **Send Transactional Email** Card
  * **SendGrid**: Fixed an issue with CC and BCC emails not being received
  * **Linear**: Fixed an issue with the integration's event handling
  * **WhatsApp**: Improved handling when the integration is rate limited by WhatsApp

  ## Bug fixes

  * **UI fixes**:
    * Fixed issue with Dashboard sidebar on mobile
    * Fixed issue where the **Copy Share Link** wasn't clickable when viewing a Workflow in the Hub

  * Fixed issue where the Capture Information Card wasn't working properly for files

  * Fixed issue where shareable Webchat link would show error screen when error hadn’t occurred

  * Fixed issue where negative feedback from Webchat wasn’t being displayed in Conversations tab
</Update>

<Update label="September 12, 2025">
  ## Features & enhancements

  * Improved the variable management experience for Autonomous Nodes:

    <Frame>
      <img alt="Autonomous Node variable management" />

      <img alt="Autonomous Node variable management" />
    </Frame>

  * Improved speed for crawling website Knowledge Bases during onboarding

  * **Integrations**:
    * **Canny:** Added Canny integration
    * **Loops:** Added Loops integration
    * **Feature Base**: Added Feature Base integration
    * **Webflow**: Added several new events

  ## Bug fixes

  * Fixed an issue where bot exports were failing
  * Fixed various UX issues in Dashboard, Studio and Webchat
  * Fixed various bugs in HubSpot integration
</Update>

<Update label="September 5, 2025">
  ## Features & enhancements

  * Improved UI for Webchat settings:

    <Tabs>
      <Tab title="General">
        <Frame>
          <img alt="General Webchat settings" />

          <img alt="General Webchat settings" />
        </Frame>
      </Tab>

      <Tab title="Theme">
        <Frame>
          <img alt="Theme Webchat settings" />

          <img alt="Theme Webchat settings" />
        </Frame>
      </Tab>
    </Tabs>

  * Fixed an issue with using additional stylesheet URLs with the Webchat React library

  * Improved speed for crawling website Knowledge Bases during onboarding

  * **Integrations:**
    * **HubSpot**: Added HubSpot integration
    * **SendGrid**: Fixed issue with API keys

  ## Bug fixes

  * Fixed an issue where bot exports were failing
  * Fixed a visual bug with the close button on Webchat error screens
</Update>

<Update label="August 29, 2025">
  ## Features & enhancements

  * Fresh layout for Dashboard bot menu:

    <Frame>
      <img alt="Dashboard layout update" />

      <img alt="Dashboard layout update" />
    </Frame>

  * Added ability to edit fields in Tables directly from the Dashboard

  * Added search option in dropdown menu to select a bot

  * Improved speed when creating new bots

  * Improvements to Studio UI:
    * Moved the Schema editor to a modal
    * Improved experience when testing a Trigger and viewing the event’s payload

  * Added [Cal.com](http://Cal.com) integration

  ## Bug fixes

  * Fixed various visual bugs in Dashboard, including on mobile
  * Fixed visual bugs in Studio:
    * UI issues with editing frozen tables
    * Workflow variable values not displaying updates in Studio
  * Fixed an issue where the Conversation Started event was emitted multiple times
  * Fixed an issue with BigCommerce integration where syncing large datasets caused a timeout
</Update>

<Update label="August 22 2025">
  ## Features & enhancements

  * Improved the Card inspector UI, which now appears in the Studio's right panel instead of obstructing your Workflow:

  <Frame>
    <img alt="Card inspector" />

    <img alt="Card inspector" />
  </Frame>

  * Improved UX for cancelling your subscription:
    * Subscription end date now displayed
    * Added a modal to give feedback when cancelling subscription
  * Improved general performance and speed for bots across the board
  * Integrations:

    * **Calendly**: Added Calendly integration
    * **Twilio**: Added support for receiving media (audio, images, videos, files)

    ## Bug fixes

    * Fixed an issue where users without the proper permissions had access to the Billing section in the Dashboard
    * Fixed minor issues with Webchat events
</Update>

<Update label="August 15, 2025">
  ## Features & enhancements

  * You can now choose any Google Font when styling Webchat:

    <Frame>
      <img alt="Search fonts" />

      <img alt="Search fonts" />
    </Frame>

  * You can now view analytics for either the current bot or the entire Workspace:

    <Frame>
      <img alt="Analytics tabs" />

      <img alt="Analytics tabs" />
    </Frame>

  * Improved syntax highlighting for logs in emulator

  ## Bug fixes

  * Fixed an issue where focusing the Webchat composer on mobile zoomed in unintentionally
  * Fixed a visual bug where multi-line inputs for integration Cards were cut off
  * Fixed a visual bug with Usage tab popovers
</Update>

<Update label="August 8, 2025">
  ## Features & enhancements

  <Frame>
    <img alt="GPT-5 in Botpress" />
  </Frame>

  * GPT-5 is now available in Botpress Studio
    * OpenAI's new GPT-OSS models are also available with Fireworks AI, Cerebras and Groq integrations
  * Various UI improvements in Studio:
    * Improved UI for integration playgrounds
    * Card tray now displays the Card type (based on the currently selected Node) and displays a message when a Card can’t be added to a Node
  * Webchat:
    * Added a `conversationId` argument to the Webchat initialization script—this allows users to programmatically load Webchat with a specific conversation
    * Improved handling of images that fail to load
  * Integrations:
    * **Messenger**: Added a playground and made general improvements
    * **Telegram:** Improved Markdown support, added support for captions on images, improved error handling
    * **Freshchat:** General fixes and improvements
    * **Zendesk:** Added the option to customize the Botpress system username in Zendesk
    * **Email:** Minor fix

  ## Bug fixes

  * Fixed an issue where conversation variables weren't usable in Capture Information Cards and Autonomous Nodes
  * Fixed an issue with searching for files based on tags in the Dashboard
  * Fixed a visual issue with filtering logs in Dashboard
</Update>

<Update label="August 1, 2025">
  ## Features & enhancements

  * Improvements to user experience in Analytics tab

  ## Bug fixes

  * Fixed an issue where Tables Cards were missing labels when added to a Node
  * Fixed an issue with missing newlines when exporting large tables as CSV
  * Fixed various visual bugs in the Dashboard
</Update>

<Update label="July 25, 2025">
  ## Features & enhancements

  * Users can now decide which members of a Workspace can access bots within that Workspace
  * Improvements to search results in the Card Tray
  * Improved UX for deleting bots in the Dashboard
  * Improvements to log filtering in the Dashboard
  * Integration updates:
    * **Email**: added a new provider-agnostic email integration
    * **HITL**: Start HITL Card now provides more specific configuration fields based on which HITL integration is being used
    * **Slack**: added support for threading in all channel types
    * **Teams**: improvements to Start DM Card

  ## Bug fixes

  * Fixed issue with testing the timeout Workflow in the emulator
  * Fixed average values for analytics
</Update>

<Update label="July 18, 2025">
  ## Features & enhancements

  * New menu for updating add-ons in Dashboard:

    <Frame>
      <img alt="Add-ons" />

      <img alt="Add-ons" />
    </Frame>

  * Updates to Dashboard Settings:
    * New section for configuration variables
    * Option to delete bot

  * Studio now displays the version of plugins

  * Improved labelling of LLMZ-appropriate models in Studio
</Update>

<Update label="July 11, 2025">
  ## Features & enhancements

  * Added a notification indicator to Webchat:

  <Frame>
    <img alt="Webchat notification" />

    <img alt="Webchat notification" />
  </Frame>

  * Improved timeout handling for integration API calls longer than 60 seconds

  * Added helpful messages to Webchat window when error occurs

  * Integration updates:
    * **SendGrid**: added support for Markdown
    * **Resend**: added CC and BCC fields to sendMail action
    * **Messenger**: added support for sending media and files
    * **Slack/WhatsApp**: improved Markdown handling

  * Added Gemini 2.5

  ## Bug fixes

  * Fixed aggregation issues for Tables API
  * Fixed an issue with renaming bots
  * Fixed an issue with Slack reply threading
</Update>

<Update label="July 4, 2025">
  ## Features & enhancements

  * **New onboarding flow**:

    When you create a new bot, Studio now has an onboarding flow that automatically builds a production-ready AI agent, styled and tailored to your brand.

    <Tabs>
      <Tab title="1. Choose a use case">
        <Frame>
          <img alt="Category" />

          <img alt="Category" />
        </Frame>
      </Tab>

      <Tab title="2. Provide knowledge sources">
        <Frame>
          <img alt="Knowledge" />

          <img alt="Knowledge" />
        </Frame>
      </Tab>

      <Tab title="3. Try out your AI agent">
        <Frame>
          <img alt="New agent" />

          <img alt="new agent" />
        </Frame>
      </Tab>
    </Tabs>

  * Screenshot Card now takes fully-styled webpage screenshots

  * Teams integration: added a Start DM Card

  ## Bug fixes

  * Fixed issue where changes to rich text Knowledge Bases weren't properly reflected
</Update>

<Update label="June 27, 2025">
  ## Features & enhancements

  * Increased timeout for crawling websites containing many pages, preventing missing pages in the Knowledge Base
  * Slack integration: Added the ability to pass a Slack `userId` to an external service

  ## Bug fixes

  * Fixed an issue where the Conversation Started Trigger wasn't firing
  * Fixed an issue with Zendesk integration where Zendesk wasn’t receiving user email addresses from the Start HITL Card
</Update>

<Update label="June 20, 2025">
  ## Features & enhancements

  * Improved uninstall flow for integrations

  ## Bug fixes

  * Fixed various issues in Studio's multiplayer
  * Fixed issue that caused user variables to be erased
  * Fixed issue with Stripe integration where payment links weren't being properly created
  * Fixed issue with Telegram integration where uploading a sticker caused an infinite loop in bot
</Update>

***

<Update label="June 13, 2025">
  ## Features & enhancements

  * Improved **AI Spend** section with a representation of each bot's usage:

    <Tabs>
      <Tab title="Total">
        <Frame>
          <img alt="AI spend total" />

          <img alt="AI spend total" />
        </Frame>
      </Tab>

      <Tab title="Daily Average">
        <Frame>
          <img alt="AI spend daily" />

          <img alt="AI spend daily" />
        </Frame>
      </Tab>
    </Tabs>

  * Added a playground for the Instagram integration

  * WhatsApp integration improvements:
    * Improved formatting for text messages
    * New dropdown label option for choice messages

  * When an HITL agent joins the chat, their messages are now sent from a distinct user

  * Added support for new models:
    * Qwen3 32B
    * Llama 4 Scout

  * Visual improvements to **Files** section in the Dashboard

  * LLMz responses now use citations

  * General improvements to RAG efficiency

  ## Bug fixes

  * Fixed issue with improper formatting when pasting into a rich text Knowledge Base
</Update>

***

<Update label="June 6, 2025">
  ## Features & enhancements

  * Webchat style refresh:

    <Frame>
      <img alt="alt" />

      <img alt="alt" />
    </Frame>

    * The new look also includes:
      * Improved animations
      * New typing indicator

  * You can now leave message feedback in Webchat:

    <Frame>
      <img alt="Webchat message feedback" />

      <img alt="Webchat message feedback" />
    </Frame>

  * Added support for new models:
    * Claude 4 Sonnet
    * DeepSeek R1 and V3
    * Llama 4

  ## Bug fixes

  * Fixed issue where users couldn’t leave the WhatsApp sandbox environment
  * Fixed issue with accessing shared drives with the Google Drive integration

  ## Miscellaneous

  * Improved error for failed payments
</Update>

***

<Update label="May 30, 2025">
  ## Features & enhancements

  * Added new Card to set a custom inactivity timeout:

    <Frame>
      <img alt="Inactivity timeout" />

      <img alt="Inactivity timeout" />
    </Frame>

  * Bumped LLM timeout from 30 seconds to 90 seconds

  * Bots using the BigCommerce integration can now recommend best-selling products without hallucinating

  ## Bug fixes

  * Fixed issue where variables assigned in the last Card in a Workflow weren’t stored
  * Various WhatsApp integration fixes:
    * Fixed error with OAuth flow when the user had more than 50 WhatsApp business accounts
    * Fixed an error when receiving [Contact](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/contacts-messages) messages from WhatsApp
  * Fixed issue with Intercom integration
</Update>

***

<Update label="May 23, 2025">
  ## Features & enhancements

  * The [Fixed Schedule](/docs/studio/concepts/triggers#fixed-schedule) Trigger now displays both the timezone and next run:

    <Frame>
      <img alt="Fixed Schedule timezone" />
    </Frame>

  * Added [Monday.com](http://Monday.com) integration

  ## Bug fixes

  * Fixed issue where Workflows incorrectly timed out under certain conditions
  * Fixed issue where proactive messages didn’t work properly for new conversations in Webchat 2.5
  * Fixed issue where tables weren’t horizontally scrollable in Webchat
  * Fixed issue where tables in Dashboard overflowed
  * Fixed issue with missing parameter in `appendValues` call to Google Sheets API
</Update>

***

<Update label="May 16, 2025">
  ## Features & enhancements

  * Fixed links to documentation in Botpress Studio
  * Added option to filter logs by message content
  * Added notifications menu in Dashboard:

    <Frame>
      <img alt="Dashboard notifications" />
    </Frame>

  ## Bug fixes

  * Fixed issue where Studio wouldn’t load under certain conditions
  * Fixed issue where you couldn’t reset FAB/avatar images to default
  * Fixed an issue where the [Conversation Started](/docs/studio/concepts/triggers#conversation-started) Trigger didn’t work within the shareable Webchat window
  * Improved rendering of Markdown in Webchat
</Update>

***

<Update label="May 9, 2025">
  ## Features & enhancements

  * **Improvements to Webchat**:
    * Now supports richer Markdown rendering
    * Webchat preview now has a sidebar with a list of recent conversations
    * You can now add an image to your Webchat’s Floating Action Button (FAB)
  * You can now filter your bot’s logs by `userId` or `conversationId`

  ## Bug fixes

  * Updated React library version and documentation

  ## Miscellaneous

  * Added a callout to Botpress Hub when the HITL plugin is required and hasn't been installed yet
</Update>

***

<Update label="May 2, 2025">
  ## Features & enhancements

  * The Slack integration now has a configuration option to **reply as a thread**:

    <Frame>
      <img alt="Slack reply threading option" />
    </Frame>

  * **HITL improvements**:
    * The Webchat composer for the HITL integration now supports **uploading files**
    * The HITL inbox now displays when the **last message** in each conversation was sent:

      <Frame>
        <img alt="HITL display last message date" />
      </Frame>

  ## Bug fixes

  * Fixed an issue where variables with circular dependencies would cause bots to crash
  * Fixed an issue where moving a Workflow or a folder inside another folder caused the tables to disappear
  * Increased duration before timeout when indexing knowledge bases with a large number of vectors

  ## Miscellaneous

  * Changed the default language setting for the WhatsApp **Start Conversation** Card to address a potential error
</Update>

***

<Update label="April 25, 2025">
  ## Features & enhancements

  * Added new models from OpenAI:
    * o4-mini
    * o3
    * 4.1
  * Users with viewer permissions for a Workspace can now view logs for that Workspace’s bots
  * Users can now upload multiple files to a single message in Webchat
  * The payload for button/dropdown components now includes the `value` of the button

  ## Bug fixes

  * Fixed an issue in Knowledge Bases  where the similarity score was in the wrong order
  * Fixed the new keyboard shortcut (`ctrl`+ `P`) for search in Studio
  * Fixed an issue where there was a mismatch with imported data
  * Fixed an issue with the default Webchat theme
  * Various fixes and improvements for the Slack integration
  * Various fixes for the BigCommerce integration
</Update>

***

<Update label="April 11, 2025">
  ## Features & enhancements

  * Revamped and improved **Usage** tab:
    * New section to track AI spend
    * Revised UI makes it clearer to understand usage between bots
  * You can now specify the storage location of Webchat user/conversation data in the Dashboard settings:
    * **Session storage**: Creates a new user/conversation every time the page is re-opened
    * **Local storage**: Keeps user/conversation data across page visits
  * Request headers for the Webhook integration are now passed into the event payload

  ## Bug fixes

  * Solved an issue where a React apps running Botpress would not run under certain circumstances
  * Fixed a bug where Human-In-The-Loop (HITL) messages were displayed in the wrong order

  ## Miscellaneous

  * Improvements to server processing so deleting bots is now faster
</Update>


# Introduction to Botpress Desk
Source: https://botpress.com/docs/desk/introduction



Botpress Desk is a **customer experience workspace for human-AI teams**. It combines a familiar interface with powerful AI-assisted tools, like:

* Suggested answers to customer messages
* Two-way translation
* Copilot that refers to your knowledge bases
* AI insights and knowledge gap reports

<Card title="Try Botpress Desk" href="https://botpress.com/contact-us?ref=docs">
  Botpress Desk is currently available upon request for <Badge>Team</Badge>, <Badge>Managed</Badge>, and <Badge>Enterprise</Badge> customers.
</Card>

<Card title="Read the Botpress Desk docs" href="https://desk.support.channel/" />

## What makes Botpress Desk different?

Botpress Desk is a support workspace built for how real support teams operate: fast triage, clear context, and human oversight that stays part of the workflow. AI helps where it's reliable, and routes to an agent when judgment matters.

## Integrations

Botpress Desk is designed for gradual adoption. We'll help you import your existing customers and data from your existing support solution, like Intercom or Zendesk.

Then, all your customer interactions sync when you take actions on either platform, so there's no risk.


# Configure your workspace
Source: https://botpress.com/docs/get-started/configure-your-workspace



In Botpress, your workspace is the environment where you organize, manage, and collaborate on your agent projects.

Each Workspace can contain multiple agents, so you can keep them organized by customer, department, or use case. Within a workspace, you can manage permissions, usage, billing, and more.

## Using multiple workspaces

Any add-ons you purchase are distributed at the workspace level, meaning that they only apply to agents in the workspace where they were purchased.

This means you can use multiple workspaces within a single account, then subscribe to different plans and add-ons for each one.

To add a new workspace:

<Steps>
  <Step>
    Select the current workspace in the upper-left corner.
  </Step>

  <Step>
    Select **+ Create a workspace**.
  </Step>

  <Step>
    Enter a name for the new workspace, then select **Create**.
  </Step>
</Steps>

<Note>
  There is no limit to the number of workspaces you can create on one account.
</Note>

## Manage your agents

You can manage all your agents in your workspace's **<Icon icon="house" /> Home** menu:

<Frame>
  <img alt="Home" />

  <img alt="Home" />
</Frame>

### Create a new agent

You can create a new agent at any time by selecting **+ Create Bot** in the upper-right corner.

### Rename an agent

To rename an existing agent, select <Icon icon="ellipsis-vertical" /> then **<Icon icon="square-pen" /> Rename**.

### Enable Always Alive&#x20;

You can enable [Always Alive](#always-alive) on any agent to keep it running continuously, even when no conversation is active. This allows for quicker response times when users first begin a conversation.

<Note>
  The number of agents you can enable Always Alive for depends on your [plan](https://botpress.com/pricing).
</Note>

### Copy an existing agent

You can copy an existing agent's configuration (including all settings and [Workflows](/docs/studio/concepts/workflows)) for any other agent:

<Steps>
  <Step>
    Select <Icon icon="ellipsis-vertical" /> on the agent you want to copy the configuration *to*.
  </Step>

  <Step>
    Select **<Icon icon="copy" /> Copy to bot**, then select the agent you want to copy *from*.
  </Step>

  <Step>
    Select **Copy**.
  </Step>
</Steps>

### Delete an agent

To delete an agent, select <Icon icon="ellipsis-vertical" /> then **<Icon icon="trash-2" /> Delete**.

## View deployed integrations

You can manage any integrations you've built and deployed to your workspace in the **<Icon icon="boxes" /> Integrations** menu.

<Note>
  If you just want to install third-party integrations, you can ignore this menu—instead, check out the official [integrations documentation](/docs/integrations/get-started/introduction).
</Note>

To learn more about building and deploying your own integrations:

<Card title="SDK" icon="hammer" href="/integrations/sdk/overview">
  Software development kit for building and deploying integrations on Botpress.
</Card>

## Track usage quotas

You can track information about usage across your workspace in the **<Icon icon="chart-pie" /> Usage** menu.

<Frame>
  <img alt="Usage" />

  <img alt="Usage" />
</Frame>

This page contains a breakdown of each type of usage quota.

<Note>
  You can always increase any limits in the [Billing menu](#billing).
</Note>

### AI Spend

Your **AI Spend** quota is the budget you allocate for your agent's usage of LLMs. This includes:

* Generating text
* Retrieving answers from Knowledge Bases
* Any other AI-powered actions

AI Spend cost is charged at cost, meaning you pay for the exact amount of tokens used by your agent without any additional markup. You can find detailed information about your agent's AI spend usage for each individual action in its [logs](/docs/studio/concepts/debugger-logs-json#logs).

<Tip>
  You can estimate your required AI Spend using our [AI Spend Calculator](https://botpress.com/ai-spend-calculator).
</Tip>

### File Storage

Your **File Storage** quota determines the storage in megabytes (MB) available across your workspace. Files included in this storage include photos, videos, and audio files that you've uploaded to be sent by your agent.

### Table Rows

Your **Table Rows** quota determines the total number of rows you can add to your agent's [Tables](/docs/studio/concepts/tables).

### Vector DB Storage

Your **Vector DB Storage** quota determines the maximum storage available for Knowledge Base documents. It accounts for the total number of vectors in all of your [Knowledge Base](/docs/studio/concepts/knowledge-base/introduction) documents, as well as searchable columns in your tables.

This value is expressed in MB for convenience, but the actual billing unit is a measure of vectorized storage, used for performing Retrieval Augmented Generation (RAG) on your Knowledge Bases.

### Incoming Messages & Events

Your **Incoming Messages & Events** quota determines the number of times your agent has been invoked in any channel and the maximum amount of times it can be invoked before it will stop responding. This includes:

* New conversations
* Conversations resumed after a [Timeout](/docs/studio/concepts/bot-settings#inactivity-timeout)
* Conversations started by [Triggers](/docs/studio/concepts/triggers).

### Collaborators

Your **Collaborators** quota determines the maximum amount of users that can collaborate in this Workspace.

### Bot Count

Your **Bot Count** quota determines the maximum number of bots this Workspace can hold. Once you reach the maximum number, you can purchase additional slots, or delete any unused bots to make room for new ones.

### Always Alive

Your **Always Alive** quota indicates how many remaining bots you can allocate the Always Alive status to.

<Accordion title="What's Always Alive?">
  Botpress agents are powered by remote, virtual compute instances. Every time your agent begins a new conversation, Botpress spins up a new instance for that agent. This is known as a *cold start*.

  During a cold start, the system must:

  * Allocate resources
  * Initialize the environment
  * Load necessary code
  * Perform any required configuration before the agent is ready to handle requests or tasks.

  Always Alive reserves an instance for your agent so that it can bypass this cold start and maintain a ready-to-use instance. The end result is that the first message sent and received from your agent are processed much faster.
</Accordion>

## Billing

You can update your billing preferences and manage your plan in the **<Icon icon="credit-card" /> Billing** menu.

<Card title="Pricing" href="https://botpress.com/pricing">
  Learn more about pricing and plans.
</Card>

### Automatically purchase add-ons

If you often find yourself having to increase a specific quota, you can automatically increase it using Auto Recharge:

<Steps>
  <Step>
    Scroll to **Add-ons**, then find the add-on you'd like to automatically increase.
  </Step>

  <Step>
    Under **Auto Recharge**, select **Disabled <Icon icon="pencil" />** to enable it for that add-on.
  </Step>
</Steps>

Now when your agent hits that specific quota, it'll adjust your plan automatically instead of notifying you.

### FAQs

<AccordionGroup>
  <Accordion title="I've changed my subscription but the changes don't seem to be reflected?">
    Because subscriptions are active throughout an entire month (or billing cycle), changes made to your subscription will appear when the next billing cycle begins.
  </Accordion>

  <Accordion title="If I purchase a plan or subscription upgrade in the middle of the month, when will I get charged?">
    Upgrades to your subscription are immediately pro-rated. If you purchase a Team plan in the middle of the month, you will pay half the value of the Team plan (for the remainder of that month), and then you will be billed as normal starting the 1st of the following month.
  </Accordion>

  <Accordion title="Where can I find Botpress invoices?">
    You can access invoices by selecting **Invoice History** in the **<Icon icon="credit-card" /> Billing** menu.
  </Accordion>

  <Accordion title="Where can I add my Tax ID?">
    You can find, edit, or update your Tax ID by selecting **Billing Information** in the **<Icon icon="credit-card" /> Billing** menu.
  </Accordion>

  <Accordion title="Where can I change which email receives receipts and invoices?">
    You can adjust billing email preferences by selecting **Billing Information** in the **<Icon icon="credit-card" /> Billing** menu.
  </Accordion>

  <Accordion title="When does AI Spend get charged?">
    All usage-based billing, like AI Spend, is charged at the end of the billing period.
  </Accordion>

  <Accordion title="Can I make purchases on Botpress even though my payment has failed?">
    No, you can't upgrade a plan or subscription if your payment fails.
  </Accordion>

  <Accordion title="When does Botpress send emails about an add-on quota that is nearing its limit?">
    Botpress sends email notifications to the owner of a Workspace when a quota has reached 75% (or more) of its usage threshold.
  </Accordion>
</AccordionGroup>

## Manage roles&#x20;

You can view and update roles for members of your workspace in **<Icon icon="settings" /> Settings** > **Members**.

Here's a breakdown of each role:

| Role                | Permissions                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| **Viewer**          | Can only view bots and Workspaces. Can't make any edits or changes                               |
| **Billing manager** | Can view and modify the Workspace's billing information                                          |
| **Developer**       | Can create, view, and update bots in the Workspace. Can only delete bots they have created       |
| **Manager**         | Can create, view, and update bots in the Workspace. Can view audit records                       |
| **Developer**       | Can add and remove Workspace collaborators, and manage all bots in the Workspace                 |
| **Owner**           | The user who creates a Workspace is automatically its owner, and has the privileges of all roles |

## View workspace activity

You can view a list of all activity that's occurred in your workspace in **<Icon icon="settings" /> Settings** > **Audits**.


# Control access to your agent
Source: https://botpress.com/docs/get-started/manage-your-agent/control-access



If you're an owner or administrator in your workspace, you can restrict who in your Workspace has access to your agent.

<Info>
  Access control requires a [Team plan](https://botpress.com/pricing) or higher.
</Info>

<Steps>
  <Step>
    Go to **<Icon icon="settings" /> Settings** in your agent's menu.
  </Step>

  <Step>
    Select **Access Control**.
  </Step>
</Steps>

Here, you can select which members of your Workspace have access to your agent:

<Frame>
  <img alt="Access control" />

  <img alt="Access control" />
</Frame>

When you're done, select **Save**.

## Access control vs. roles

Access control is an *agent-level setting*—it doesn't change the workspace member's access to any other agents or their overall role in the workspace. You can configure workspace-level roles in your [Workspace settings](/docs/get-started/configure-your-workspace#manage-roles).

<Note>
  Workspace owners and administrators always have access to all bots in a workspace.
</Note>


# Edit appearance
Source: https://botpress.com/docs/get-started/manage-your-agent/edit-appearance



You can configure your agent's appearance using its Webchat configuration:

<Card title="Style your agent" icon="settings-2" href="/webchat/get-started/configure-your-webchat">
  Check out the Webchat documentation for more information on configuring and styling your agent.
</Card>


# Configure Human Handoff
Source: https://botpress.com/docs/get-started/manage-your-agent/human-handoff



If you want to allow a live agent to join your agent's conversations, you can configure this in the **<Icon icon="message-square-reply" /> Human Handoff** section of your bot's menu.

<Warning>
  For new workspaces, Human Handoff has moved to [Botpress Desk](https://botpress.com/desk), our new AI helpdesk for modern support teams. Go to **Human Handoff > Open Botpress Desk** to get started setting up your workspace.

  Users on existing workspaces can follow the steps below and continue using the legacy HITL integration.
</Warning>

## Setup

To get started using Human Handoff, you need to install and configure the official Human-in-the-Loop (HITL) integration:

<Card title="Configure HITL" href="/integrations/integration-guides/hitl/introduction" icon="plug">
  Install and configure the official integration <Tooltip><Badge>Plus</Badge></Tooltip>
</Card>

When you've finished setting up the integration, you'll have access to the Human Handoff **Dashboard**.

***

## Dashboard

When you've finished setting up the integration, you'll have access to the Human Handoff **Dashboard**. Here's how it works:

### View your tickets

When a user triggers Human Handoff, a ticket is opened. You can view your tickets in the left sidebar:

<Frame>
  <img alt="Pending conversation" />

  <img alt="Pending conversation" />
</Frame>

Select any ticket to view the conversation with the user.

<Tip>
  You can use the drop-down menus to filter your tickets by their status.
</Tip>

### Assign a ticket

You can assign a ticket to anyone in your Workspace, including yourself. For example, select **<Icon icon="user-round" /> Assign to me**:

<Frame>
  <img alt="Assign conversation" />

  <img alt="Assign conversation" />
</Frame>

Now you can chat directly with the user:

<Frame>
  <img alt="Respond to user" />

  <img alt="Respond to user" />
</Frame>

### Close a ticket

When you've resolved the conversation with the user, select **Resume Chatbot <Icon icon="undo-2" />**. This removes you from the conversation and lets the user keep chatting with your agent.

## Testing

You can test Human Handoff by using your agent's preview to simulate an escalation.

<Steps>
  <Step>Open your agent's [preview](/docs/get-started/manage-your-agent/preview).</Step>

  <Step>
    Chat with your agent until it triggers Human Handoff:

    <Frame>
      <img alt="Trigger Human Handoff" />

      <img alt="Trigger Human Handoff" />
    </Frame>
  </Step>

  <Step>
    Navigate to the Dashboard, then go to the bot's **<Icon icon="message-square-reply" /> Human Handoff** menu. From there, you can assign and interact with the ticket.
  </Step>
</Steps>


# Inspect behaviour
Source: https://botpress.com/docs/get-started/manage-your-agent/inspect



You can inspect your agent's behaviour in the **<Icon icon="bug" /> Inspect** section of your agent's menu. Here's a breakdown of each sub-section:

## Logs

You can view logs from all your agent's conversations in the **Logs** sub-section. This includes system logs that provide updates on your agent's status, as well as logs from any integrations you have installed:

<Frame>
  <img alt="Logs" />

  <img alt="Logs" />
</Frame>

You can filter logs by date and time to narrow down your search for a specific event or conversation.

### Custom logs

You can add custom logs when [writing code in Studio](/docs/studio/guides/advanced/use-code)—just use JavaScript's `console.log`:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
console.log('An error occured.')
```

Once you’ve published your changes, your bot will print that statement to its logs every time the code executes.

***

## Events

Events represent what happens within your bot, such as messages from users and system-level occurrences. You can view all incoming events processed by your agent in the **Events** section:

<Frame>
  <img alt="Events" />

  <img alt="Events" />
</Frame>

<Accordion title="What counts as an event?">
  An event is any action that triggers bot activation. Only incoming messages & events that a bot listens to count towards your event quota.

  The following actions count as an incoming message & event:

  * A user saying "Hello" to a bot
  * A reaction being added to a message
  * A [Trigger](/docs/studio/concepts/triggers) that opens the bot
  * A session timeout event
  * Opening the bot's shareable URL
  * Publishing your bot (counts as 3 events)

  The following actions don't count as an incoming message & event:
  ‍

  * A message sent by the bot in response to a user message
  * An execute code card
  * [Workflow](/docs/studio/concepts/workflows) transitions
</Accordion>

### Event data

Select any event to view a detailed JSON representation of all its associated data:

<Frame>
  <img alt="Event JSON data" />

  <img alt="Event JSON data" />
</Frame>

### Quota

Incoming events count towards your plan's Incoming Messages & Events quota. If you need to increase this quota, go to the [Billing](/docs/get-started/configure-your-workspace/#billing) section.

***

## Files

You can view all files uploaded to your agent in the **Files** section. This includes:

* [Files uploaded by users](/docs/webchat/get-started/configure-your-webchat#features)
* Files indexed as part of a [Knowledge Base](/docs/get-started/manage-your-agent/knowledge#knowledge-bases)
* System files
* Files you've uploaded yourself using the [Files API](/docs/api-reference/files-api/getting-started)

### Inspect file data

Select any file to view a detailed JSON representation of all its associated data:

<Frame>
  <img alt="File JSON data" />

  <img alt="File JSON data" />
</Frame>

### View a file

To view a file, select it and open its URL.

### Download a file

To download a file, select <Icon icon="ellipsis-vertical" /> to open additional options, then <Icon icon="download" /> **Download**.

### Delete a file

To delete a file,  select <Icon icon="ellipsis-vertical" /> to open additional options, then <Icon icon="trash-2" /> **Delete**.

### Quota

Any files you store count against your File Storage quota. You can increase your quota in your dashboard's [Billing](/docs/get-started/configure-your-workspace#billing) menu.

***

## Issues

You can view any problems or errors your agent encountered in the **Issues** sub-section:

<Frame>
  <img alt="Issues" />

  <img alt="Issues" />
</Frame>

The **Category** field tells you where the issue came from, while the **Events** field tells you how many times it occurred. Select any issue to view a list of all occurrences:

<Frame>
  <img alt="Issue events" />

  <img alt="Issue events" />
</Frame>

This gives you detailed information about each occurrence, like:

* Its payload
* The associated user and conversation IDs
* The channel or integration on which it occurred


# Add knowledge sources
Source: https://botpress.com/docs/get-started/manage-your-agent/knowledge



You can add and manage knowledge sources in the **<Icon icon="book-open-text" /> Knowledge** section of your agent's menu. Here's a breakdown of each sub-section:

## Tables

You can view data your agent has stored in the **Tables** sub-section. Select any table to view its contents.

<Note>
  You can [create new tables in Studio](/docs/studio/concepts/tables) if you want your agent to store custom data.
</Note>

***

## Knowledge Bases

You can manage which sources your bot has access to in the **Knowledge Bases** sub-section.

Every new agent has a default empty Knowledge Base. Open it, then select **+ Add Knowledge Source** to provide your agent with new sources—it'll automatically reference them when answering users.

<Tip>
  You can also select **+ Add Knowledge Base** to create an entirely new Knowledge Base.
</Tip>

### Manage website indexing

To manage a website Knowledge Base's indexing/recrawling options, open it and select **<Icon icon="ellipsis" /> Manage**. You can:

* **Reconfigure**: Change the recrawling frequency (how often the Knowledge Base updates)
* **Resync**: Trigger a manual recrawl of the website
* **Remove this source**: Remove the source from the Knowledge Base

### Configure in Studio

If you need more control over your Knowledge Bases, you can [configure them in Studio](/docs/studio/concepts/knowledge-base/introduction). This gives you access to advanced options for each [type of source](/docs/studio/concepts/knowledge-base/add-sources).

### Storage

When you add and use knowledge sources, it counts towards your File Storage and Vector DB Storage. You can see an overview of your current usage at the top of the section.

If you need additional storage, select **Add Storage**. Check out our [pricing page](https://botpress.com/pricing) for more details.


# Monitor performance
Source: https://botpress.com/docs/get-started/manage-your-agent/monitor



You can monitor your agent's performance in the **<Icon icon="chart-spline" /> Monitor** section of your agent's menu. Here's a breakdown of each sub-section:

## Conversations

You can view a list of all your agent's conversations in the **Conversations** sub-section. Just select any conversation to view its details:

<Frame>
  <img alt="Conversation" />

  <img alt="Conversation" />
</Frame>

In this menu, you can access:

* The conversation's participants
* Its conversation ID
* Which integration it occurred on
* Its start date and last activity
* Its current status
* Any tags associated with it

### Message data

You can select any message in the conversation to get a detailed JSON representation of all its associated data:

<Frame>
  <img alt="Message JSON data" />

  <img alt="Message JSON data" />
</Frame>

### AI insights&#x20;

Select **<Icon icon="sparkles" /> Enable AI** to enable sentiment analysis and AI summaries for incoming conversations:

<Frame>
  <img alt="AI insights" />

  <img alt="AI insights" />
</Frame>

***

## Users

You can view all your agent's unique users in the **Users** sub-section. Select any user ID to open [conversations](#conversations), [events](/docs/get-started/manage-your-agent/inspect#events), or [logs](/docs/get-started/manage-your-agent/inspect#logs) associated with that user.

## Analytics

You can view detailed analytics about your agent's performance in the **Analytics** sub-section:

<Frame>
  <img alt="Analytics" />

  <img alt="Analytics" />
</Frame>

For any tile, you can:

* Select the current range <Icon icon="calendar" /> to modify it
* Select **Edit Source** <Icon icon="chart-column" /> to change which data the tile displays
* Select <Icon icon="ellipsis-vertical" /> to access additional options:
  * **Show/Hide Legend**
  * **Type**
  * **Duplicate**
  * **Delete**


# Preview
Source: https://botpress.com/docs/get-started/manage-your-agent/preview



You can chat with a preview of your published agent at any time:

<Steps>
  <Step>Go to the **<Icon icon="layout-panel-left" /> Overview** section in your agent's menu.</Step>

  <Step>
    Select **<Icon icon="external-link" /> Preview** to open the preview.
  </Step>
</Steps>

## Test your agent

Start a conversation with your agent and test its behaviour:

<Frame>
  <img alt="Preview" />

  <img alt="Preview" />
</Frame>

## Styling

The preview is generated using [Webchat](/docs/webchat/get-started/introduction), Botpress' custom frontend. It shows how your agent will appear to users when you add it to your website.

For more information about styling your agent:

<Card title="Style your agent" icon="settings-2" href="/webchat/get-started/configure-your-webchat">
  Configure your agent's appearance using Webchat.
</Card>


# Quickstart
Source: https://botpress.com/docs/get-started/quick-start

Build, test, and deploy your first AI agent.

It's easy to build an AI agent on Botpress in just a few minutes, regardless of your level of development experience.

By the end of this guide, you'll have a bot that:

* Uses AI to respond to messages
* Aligns with your branding
* Has a unique, shareable link

<Tip>
  Visual learner? Check out our [platform walkthrough on YouTube](https://www.youtube.com/watch?v=41U-ofr7MxE).
</Tip>

## Step 1: Build your bot

<Steps>
  <Step>[Sign up for Botpress](https://sso.botpress.cloud/login).</Step>
  <Step>Select either **Start building** or **Build my agent**.</Step>
  <Step>Follow the on-screen instructions to configure your first bot. We'll take care of everything for you, and your AI agent will be ready to test and deploy within minutes.</Step>
</Steps>

<Note>
  If you'd prefer to set your bot up from scratch, hit **Skip** and head over to the [tutorial](/docs/tutorial/introduction)—we'll show you how to start building with Botpress Studio.
</Note>

## Step 2: Fine-tune your bot (Optional)

After completing the setup process, we'll show you a preview of your bot, trained on your sources and styled to match to your brand. Try chatting with your bot—you may want to keep it as-is!

If you need to fine-tune anything, check out the resources below:

### Appearance and style

The preview we show you is built using [Webchat](/docs/webchat/get-started/introduction), Botpress' custom front-end. If you want to customize your bot's appearance and style, you can configure its Webchat settings:

<Card title="Edit appearance" icon="paintbrush" href="/webchat/get-started/configure-your-webchat">
  Configure and style your bot
</Card>

### Behaviour

After completing the setup process, you might realize you need to fine-tune your bot's behaviour. Maybe you forgot to provide a certain knowledge source, or want to tweak its instructions.

You can do this with [Botpress Studio](/docs/studio/introduction), our agent-building platform. Check out Studio concepts to learn more about them, or start from scratch with the tutorial:

<CardGroup>
  <Card title="Studio concepts" icon="share-2" href="/studio/introduction">
    Find information about concepts from Botpress Studio
  </Card>

  <Card title="Tutorial" icon="chef-hat" href="/tutorial/introduction">
    Learn the basics of Botpress Studio by building a bot
  </Card>
</CardGroup>

## Step 3: Deploy your bot

When you're ready to deploy your bot, select one of the options below:

<CardGroup>
  <Card title="Add to your website" icon="message-square" href="/webchat/get-started/introduction">
    Use Webchat to embed your bot on your website
  </Card>

  <Card title="Integrate with a channel" icon="plug" href="/integrations/get-started/introduction">
    Integrate your bot with another channel or external service
  </Card>
</CardGroup>

<Check>
  You just built and deployed your first bot with Botpress!
</Check>


# Welcome to Botpress
Source: https://botpress.com/docs/index



<div>
  <div>
    <h1>
      Documentation
    </h1>

    <div>
      Learn how to use Botpress, the complete AI agent platform.
    </div>

    <div>
      <button>
        <div>
          <img alt="bolt icon" />

          <span>Ask AI</span>
        </div>
      </button>

      <a href="https://discord.gg/botpress">
        <div>Get help</div>
      </a>
    </div>
  </div>
</div>

<div>
  <div>
    <Card title="ADK" href="/adk/introduction">
      TypeScript library for building AI agents from code
    </Card>
  </div>

  <div>
    <Card title="Studio" href="/studio/introduction">
      Visual, drag-and-drop interface for building AI agents
    </Card>
  </div>

  <div>
    <Card title="Botpress Desk" href="https://desk.support.channel/">
      Customer support workspace for human-AI teams
    </Card>
  </div>
</div>

<div>
  <div>
    <WebchatCard />
  </div>

  <div>
    <IntegrationsCard />
  </div>
</div>


# Botpress Hub
Source: https://botpress.com/docs/integrations/get-started/botpress-hub

Marketplace to find and install integrations.

Botpress Hub is a **marketplace for integrations**. You can browse the Hub to find:

* Pre-built integrations by Botpress
* Third-party integrations
* Useful Workflows and plugins for your bot

<Note>
  Want to build your own integration and publish it on Botpress Hub? Check out the [For Developers](/docs/integrations/sdk/overview) section.
</Note>

## Access Botpress Hub

To access Botpress Hub, select <Icon icon="boxes" /> **Explore Hub** in the upper-right corner of the [Studio](/docs/studio/introduction).

## Install an integration

Use the search bar or filters to find an integration:

<img alt="Search Botpress Hub" />

Then, select **Install Integration** to install it to your bot:

<img alt="Install integration" />

## Configure your integration

After installing an integration, you usually need to configure it before you can start using it:

<img alt="Configure an integration" />

The exact configuration steps will vary depending on which integration you're trying to setup.


# Introduction to integrations
Source: https://botpress.com/docs/integrations/get-started/introduction

Connect your bot to external services.

Integrations allow you to **connect your bot** to external services, APIs, and tools.

You can explore any available integrations on [Botpress Hub](/docs/integrations/get-started/botpress-hub), which includes integrations built by both Botpress and by users.

<Note>
  Want to build your own integration and publish it on [Botpress Hub](/docs/integrations/get-started/botpress-hub)? Check out our [integrations SDK](/docs/integrations/sdk/integration/getting-started).
</Note>

## Get Started

<Card title="Botpress Hub" icon="boxes" href="/integrations/get-started/botpress-hub">
  Marketplace to find and install integrations
</Card>

## Popular integrations

<CardGroup>
  <Card title="WhatsApp" icon="whatsapp" href="/integrations/integration-guides/whatsapp/">
    Integrate your bot with WhatsApp
  </Card>

  <Card title="Telegram" icon="telegram" href="/integrations/integration-guides/telegram/">
    Integrate your bot with Telegram
  </Card>

  <Card title="Messenger" icon="facebook-messenger" href="/integrations/integration-guides/messenger/">
    Integrate your bot with Messenger
  </Card>
</CardGroup>


# Apollo
Source: https://botpress.com/docs/integrations/integration-guides/apollo

Add a bot to Apollo using the official integration.

<OpenInHub />

The official Apollo integration allows your bot to create, enrich, update or search your Apollo contacts.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * An [Apollo account](https://www.apollo.io/sign-up)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Apollo.io** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API Key**. Leave it empty for now—you'll come back to it after creating your Apollo API key.
  </Step>

  <Step title="Create an Apollo API key">
    Next, create an Apollo API key:

    1. [Log in to your Apollo account](https://app.apollo.io/#/login).

    2. Select **Admin Settings** from the bottom-left corner.

    3. Select **Integrations**.

    4. Scroll all the way down and select **API**.

    5. From the left navigation bar, select **API Keys**.

    6. Fill out the required fields. From the **APIs** drop-down, select:

       * `api/v1/people/match`
       * `api/v1/people/bulk_match`
       * `api/v1/contacts/create`
       * `api/v1/contacts/update`
       * `api/v1/contacts/search`

    7. Select **Create API key**, then copy the generated key.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your apollo API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Apollo integration is ready. You can use the integration's [Cards](#cards) to interact with your Apollo subscribers.
</Check>

***

## Cards

<Note>
  Any enrichment operations you perform consume credits from your [Apollo pricing plan](https://www.apollo.io/pricing).
</Note>

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Bulk Enrich People

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="apiResponse" type="object" />
  </Expandable>
</ResponseField>

### Create Contact

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="apiResponse" type="object" />
  </Expandable>
</ResponseField>

### Enrich Person

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="apiResponse" type="object" />
  </Expandable>
</ResponseField>

### Search Contacts

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="apiResponse" type="object" />
  </Expandable>
</ResponseField>

### Update Contact

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="apiResponse" type="object" />
  </Expandable>
</ResponseField>


# Asana
Source: https://botpress.com/docs/integrations/integration-guides/asana



<OpenInHub />

Asana Integration allows you to seamlessly connect your Botpress and Asana, a well-established project management platform. This integration equips your bot with the ability to manage projects and tasks right from its interface. After the setup, you will be able to perform actions such as task creation, task updates, task comment addition, and more.

## Prerequisites

* An [Asana account](https://asana.com/)
* Access to an existing Asana workspace.

## Setting up the Asana integration in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Asana integration then click on the "Install to Bot" button, now go back to your bot settings.

The Asana integration has the following settings:

* **Enabled**: Whether Botpress will communicate with Asana
* **Webhook URL**: The URL for receiving data in Botpress. (You shall not be using it)
* **API Token**: The API token generated from Asana
* **Workspace Gid**: The workspace ID obtained from Asana

## Setting up Asana

1. Generate a Personal Access Token on Asana. Follow [these instructions](https://developers.asana.com/docs/personal-access-token) to get your token. Once you have it, paste it in the API Token input in Botpress.
2. Get the workspace ID. You can obtain your workspace ID by visiting [this link](https://app.asana.com/api/1.0/workspaces) while logged in to your Asana account. The workspace ID corresponds to the `gid` parameter of the workspace you want to use. Paste it in the Workspace Gid input in Botpress.

That's it! Now the Asana integration is operational and ready for use within your bot.

<Note>
  Note

  The Asana API rate limits are applicable. Also, note that certain advanced Asana features tied to paid plans may not be accessible.
</Note>

With the Asana Integration, you can interact with Asana directly from your Botpress bot. The integration introduces various actions, including task creation, task updates, task comment addition, and more, making the task and user management processes more efficient.

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add Comment to Task

### Create Task

### Find User

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="photo" type="object | null" />
  </Expandable>
</ResponseField>

### Update Task


# Attio
Source: https://botpress.com/docs/integrations/integration-guides/attio

Add a bot to Attio using the official integration.

<OpenInHub />

The official Attio integration allows your bot to interact with objects/records in your Attio workspace.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Attio account](https://app.attio.com/welcome/sign-in)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Attio** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **Access Token**. Leave it empty for now—you'll come back to it after creating your Attio API token.
  </Step>

  <Step title="Create an Attio API token">
    Next, create a Attio API token:

    1. [Log in to your Attio account](https://app.attio.com/welcome/sign-in).
    2. Select your workspace name in the upper-left corner. Then, select **Workspace settings**.
    3. From the left navigation bar, select **Developers**.
    4. Select **+ Create access token**. Enter a name, then enable the following scopes:
       * **Object configuration**: Read access
       * **Records**: Read/write access
    5. Select **Save changes**, then copy the token.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **Access Token** field, paste your Attio API token.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Attio integration is ready. You can use the integration's [Cards](#cards) to interact with your Attio objects and records..
</Check>

## Cards

<Note>
  When adding [filters](#param-filter) to the [List Records](#list-records) Card, follow [Attio's filtering guide](https://docs.attio.com/rest-api/how-to/filtering-and-sorting) to structure your data.
</Note>

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Record

### Get Object

### Get Record

### List Attributes

### List Objects

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### List Records

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="sorts" type="array">
      <Expandable title="array item properties">
        <ResponseField name="direction" type="enum<string>">
          Available options: `asc`, `desc`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Update Record

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Record Created

### Record Deleted

### Record Updated


# BambooHR
Source: https://botpress.com/docs/integrations/integration-guides/bamboohr

Add a bot to BambooHR using the official integration.

<OpenInHub />

The official BambooHR integration allows your bot to interact with your company's BambooHR employees.

## Setup

<Info>
  You will need:

  * A [published bot](https://botpress.com/docs/get-started/quickstart)
  * A [BambooHR account](https://www.bamboohr.com/pl-pages/intl-en/bamboohr-software?s_kwcid=AL!18332!3!756232856072!e!!g!!bamboohr\&utm_campaign=BAMB-DG-Search-BambooHR-Bamboo-INT-AdAi-2024EG\&utm_medium=cpc\&utm_source=google\&utm_content=blank\&utm_term=blank\&CampaignID=22634976683\&AdGroupID=180133835709\&ClickID=EAIaIQobChMIlO26zKrFkAMVTHWeBx0o3TqgEAAYASAAEgL9yfD_BwE\&MatchType=e\&Keyword=bamboohr\&Device=c\&AdID=756232856072\&Network=g\&bt=756232856072&_bk=bamboohr&_bm=e&_bn=g&_bg=180133835709\&gad_source=1\&gad_campaignid=22634976683\&gclid=EAIaIQobChMIlO26zKrFkAMVTHWeBx0o3TqgEAAYASAAEgL9yfD_BwE)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **BambooHR** integration, then select **Install Integration**.
    3. In the drop-down menu, select **Configure manually with your BambooHR API Key**.
    4. Fill the **BambooHR Subdomain** field with your company's subdomain (`https://mycompany.bamboohr.com`)
    5. Leave the **API Key** field blank for now—you'll come back to it after getting your BambooHR API key.
  </Step>

  <Step title="Get your BambooHR API key">
    Next, get your BambooHR API key:

    1. [Log in to BambooHR](https://app.bamboohr.com/login/).
    2. Select your avatar in the bottom-left corner, then select **API Keys**.
    3. Select **+ Add New Key**.
    4. Enter a name for the API key, then select **Generate Key**.
    5. Copy the generated key.

    <Note>
      If you get an error when trying to access the API keys menu (or can't see the option to add a new key), make sure you have sufficient permissions in your company's BambooHR account.
    </Note>
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your BambooHR API key.
    2. Select **Save configuration**.
  </Step>
</Steps>

<Check>
  Your BambooHR integration is ready. You can use the integration's [Cards](#cards) and [Triggers](#triggers) to interact with your company's employees.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get Company Info

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="address" type="object">
      <Expandable>
        <ResponseField name="line1" type="string | null" />

        <ResponseField name="line2" type="string | null" />

        <ResponseField name="city" type="string | null" />

        <ResponseField name="state" type="string | null" />

        <ResponseField name="country" type="string | null" />

        <ResponseField name="zip" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="phone" type="string | null" />
  </Expandable>
</ResponseField>

### Get Basic Info

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="customBenefitIDNumber" type="string | null" />

    <ResponseField name="customCitizenshipCertificate" type="string | null" />

    <ResponseField name="payChangeReason" type="string | null" />

    <ResponseField name="payRateEffectiveDate" type="string | null" />

    <ResponseField name="department" type="string | null" />

    <ResponseField name="division" type="string | null" />

    <ResponseField name="employeeNumber" type="string | null" />

    <ResponseField name="employeeTaxType" type="string | null" />

    <ResponseField name="employmentHistoryStatus" type="string | null" />

    <ResponseField name="employeeStatusDate" type="string | null" />

    <ResponseField name="ethnicity" type="string | null" />

    <ResponseField name="facebook" type="string | null" />

    <ResponseField name="firstName" type="string | null" />

    <ResponseField name="gender" type="string | null" />

    <ResponseField name="hireDate" type="string | null" />

    <ResponseField name="homeEmail" type="string | null" />

    <ResponseField name="homePhone" type="string | null" />

    <ResponseField name="jobTitle" type="string | null" />

    <ResponseField name="lastName" type="string | null" />

    <ResponseField name="linkedIn" type="string | null" />

    <ResponseField name="location" type="string | null" />

    <ResponseField name="maritalStatus" type="string | null" />

    <ResponseField name="middleName" type="string | null" />

    <ResponseField name="mobilePhone" type="string | null" />

    <ResponseField name="customNIN1" type="string | null" />

    <ResponseField name="nationality" type="string | null" />

    <ResponseField name="originalHireDate" type="string | null" />

    <ResponseField name="overtimeRate" type="string | null" />

    <ResponseField name="exempt" type="string | null" />

    <ResponseField name="payPer" type="string | null" />

    <ResponseField name="paySchedule" type="string | null" />

    <ResponseField name="payRate" type="string | null" />

    <ResponseField name="payType" type="string | null" />

    <ResponseField name="preferredName" type="string | null" />

    <ResponseField name="customProbationaryPeriodEndDate" type="string | null" />

    <ResponseField name="customProbationaryPeriodStartDate" type="string | null" />

    <ResponseField name="customProjectedTerminationDate" type="string | null" />

    <ResponseField name="customROESATCompleted" type="string | null" />

    <ResponseField name="reportsTo" type="string | null" />

    <ResponseField name="customShirtsize" type="string | null" />

    <ResponseField name="status" type="string | null" />

    <ResponseField name="teams" type="string | null" />

    <ResponseField name="customTerminationCode" type="string | null" />

    <ResponseField name="customTerminationNoticeGiven" type="string | null" />

    <ResponseField name="twitterFeed" type="string | null" />

    <ResponseField name="workEmail" type="string | null" />

    <ResponseField name="workPhoneExtension" type="string | null" />

    <ResponseField name="workPhone" type="string | null" />

    <ResponseField name="supervisorEid" type="string | null" />
  </Expandable>
</ResponseField>

### Get Custom Info

### Get Employee Fields

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### List Employees

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Employee Created

### Employee Deleted

### Employee Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="fields" type="object">
      <Expandable>
        <ResponseField name="customBenefitIDNumber" type="string | null" />

        <ResponseField name="customCitizenshipCertificate" type="string | null" />

        <ResponseField name="payChangeReason" type="string | null" />

        <ResponseField name="payRateEffectiveDate" type="string | null" />

        <ResponseField name="department" type="string | null" />

        <ResponseField name="division" type="string | null" />

        <ResponseField name="employeeNumber" type="string | null" />

        <ResponseField name="employeeTaxType" type="string | null" />

        <ResponseField name="employmentHistoryStatus" type="string | null" />

        <ResponseField name="employeeStatusDate" type="string | null" />

        <ResponseField name="ethnicity" type="string | null" />

        <ResponseField name="facebook" type="string | null" />

        <ResponseField name="firstName" type="string | null" />

        <ResponseField name="gender" type="string | null" />

        <ResponseField name="hireDate" type="string | null" />

        <ResponseField name="homeEmail" type="string | null" />

        <ResponseField name="homePhone" type="string | null" />

        <ResponseField name="jobTitle" type="string | null" />

        <ResponseField name="lastName" type="string | null" />

        <ResponseField name="linkedIn" type="string | null" />

        <ResponseField name="location" type="string | null" />

        <ResponseField name="maritalStatus" type="string | null" />

        <ResponseField name="middleName" type="string | null" />

        <ResponseField name="mobilePhone" type="string | null" />

        <ResponseField name="customNIN1" type="string | null" />

        <ResponseField name="nationality" type="string | null" />

        <ResponseField name="originalHireDate" type="string | null" />

        <ResponseField name="overtimeRate" type="string | null" />

        <ResponseField name="exempt" type="string | null" />

        <ResponseField name="payPer" type="string | null" />

        <ResponseField name="paySchedule" type="string | null" />

        <ResponseField name="payRate" type="string | null" />

        <ResponseField name="payType" type="string | null" />

        <ResponseField name="preferredName" type="string | null" />

        <ResponseField name="customProbationaryPeriodEndDate" type="string | null" />

        <ResponseField name="customProbationaryPeriodStartDate" type="string | null" />

        <ResponseField name="customProjectedTerminationDate" type="string | null" />

        <ResponseField name="customROESATCompleted" type="string | null" />

        <ResponseField name="reportsTo" type="string | null" />

        <ResponseField name="customShirtsize" type="string | null" />

        <ResponseField name="status" type="string | null" />

        <ResponseField name="teams" type="string | null" />

        <ResponseField name="customTerminationCode" type="string | null" />

        <ResponseField name="customTerminationNoticeGiven" type="string | null" />

        <ResponseField name="twitterFeed" type="string | null" />

        <ResponseField name="workEmail" type="string | null" />

        <ResponseField name="workPhoneExtension" type="string | null" />

        <ResponseField name="workPhone" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Canny
Source: https://botpress.com/docs/integrations/integration-guides/canny

Add a bot to Canny using the official integration.

<OpenInHub />

The official Canny integration allows your bot to manage posts and comments in your Canny feature request boards.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Canny account](https://canny.io/register)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Canny** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API key**. Leave it empty for now—you'll come back to it after getting your Canny API key.
  </Step>

  <Step title="Get your Canny API key">
    Next, get your Canny API key:

    1. [Log in to your Canny dashboard](https://canny.io/login).
    2. In the top-right corner, select your profile icon and go to **Settings**.
    3. From the left sidebar, go to **API**.
    4. Copy your API key.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your Canny API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Canny integration is ready. You can use the integration's [Cards](#cards) to interact with your Canny account.
</Check>

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Comment

### Create or Update User

### Create Post

### Delete Comment

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Post

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Get Comment

### Get Post

### List Boards

### List Comments

### List Posts

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="sort" type="enum<string>">
      Available options: `newest`, `oldest`, `relevance`, `score`, `statusChanged`, `trending`
    </ResponseField>
  </Expandable>
</ResponseField>

### List Users

### Update Post

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>


# Chat
Source: https://botpress.com/docs/integrations/integration-guides/chat



<OpenInHub />

The official Chat integration offers an **HTTP API to chat with your bot**.

<Card title="Chat API" icon="chevrons-left-right" href="/api-reference/chat-api/">
  Check out the Chat API documentation for more information
</Card>


# Chatwoot
Source: https://botpress.com/docs/integrations/integration-guides/chatwoot

Add a bot to Chatwoot using the official integration.

<OpenInHub />

The official Chatwoot integration allows users to chat with your bot through Telegram, WhatsApp, Email, or any Chatwoot-supported channel. It also allows your bot to hand off conversations to human agents when needed.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Chatwoot account](https://app.chatwoot.com/app/auth/signup?utm_source=navbar-link)
</Info>

### Step 1: Install the integration in Botpress

<Steps>
  <Step>
    In Botpress Studio, select **Explore Hub** in the upper-right corner.
  </Step>

  <Step>
    Search for the **Chatwoot** integration, then select **Install Integration**.
  </Step>

  <Step>
    In the **Configuration** menu, you should see three fields:

    * **API Access Token**
    * **Account ID**
    * **Inbox ID**
  </Step>
</Steps>

### Step 2: Get your credentials from Chatwoot

Log in to Chatwoot. Then, in Botpress, fill in the integration's configuration fields using information from your Chatwoot account:

<AccordionGroup>
  <Accordion title="API Access Token">
    <Steps>
      <Step>
        In Chatwoot, select your profile icon (bottom-left corner).
      </Step>

      <Step>
        Go to **Profile Settings**.
      </Step>

      <Step>
        Scroll to the **Access Token** section.
      </Step>

      <Step>
        Copy the token, then paste it into the **API Access Token** field in Botpress.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Account ID">
    <Steps>
      <Step>
        In the Chatwoot page's URL, find and copy your account ID—it should be after `/accounts/`.

        For example, if your page URL is:

        `https://app.chatwoot.com/app/accounts/145294/...`

        the account ID is:

        `145294`.
      </Step>

      <Step>
        Paste the account ID into the **Account ID** field in Botpress.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Inbox ID">
    <Steps>
      <Step>
        In Chatwoot, go to **Settings > Inboxes**.
      </Step>

      <Step>
        Select **Add Inbox**.
      </Step>

      <Step>
        Select **API** as the channel type.
      </Step>

      <Step>
        Choose a name for the channel.
      </Step>

      <Step>
        After creation, select the inbox to open its settings.
      </Step>

      <Step>
        In the Chatwoot page's URL, find and copy your inbox ID—it should be after `/inboxes/`.

        For example, if your page URL is:

        `https://app.chatwoot.com/app/accounts/1/settings/inboxes/88275`

        the inbox ID is `88275`.
      </Step>

      <Step>
        Paste the inbox ID into the **Inbox ID** field in Botpress.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

### Step 3: Configure your webhook in Chatwoot.

Finally, configure your Botpress webhook in Chatwoot:

<Steps>
  <Step>
    In Botpress, copy the integration's webhook URL (starting with `https://webhook.botpress.cloud`).
  </Step>

  <Step>
    In Chatwoot, go to **Settings > Integrations > Webhooks**.
  </Step>

  <Step>
    Select **Add New Webhook**.
  </Step>

  <Step>
    Paste the Botpress webhook URL.
  </Step>

  <Step>
    Select the following events:

    * `message_created`
    * `conversation_status_changed`
  </Step>

  <Step>
    Select **Create Webhook**.
  </Step>
</Steps>

<Check>
  Your Chatwoot integration is ready. When users send a message to the provided Chatwoot inbox, it'll respond as your Botpress bot.
</Check>


# Discord
Source: https://botpress.com/docs/integrations/integration-guides/discord

Add your bot to Discord using the official integration.

<OpenInHub />

The official Discord integration allows users to chat with your bot in Discord servers, threads, and direct messages.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Discord account](https://discord.com/) with permission to create applications
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Discord** integration.
    3. Select **Install Integration**.

    In the **Configuration** menu, you should see one field:

    * **Bot Token**

    Leave it empty for now—you'll come back to it after completing the setup in Discord.
  </Step>

  <Step title="Create a Discord application">
    Next, create a Discord application:

    1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and sign in.
    2. Select **New Application** in the top-right corner.
    3. Give your application a name and select **Create**.
  </Step>

  <Step title="Create a bot user">
    Now, create a bot user for your application:

    1. In your application's left sidebar, select **Bot**.
    2. Under the bot's username, you can optionally set a custom avatar and display name.
    3. Under **Privileged Gateway Intents**, enable the following:
       * **Server Members Intent**
       * **Message Content Intent**
    4. Select **Save Changes**.
  </Step>

  <Step title="Copy your bot token">
    Next, copy your bot's token:

    1. Still on the **Bot** page, below **Token**, select **Reset Token** (or **Copy** if a token is already visible).
    2. Confirm the reset if prompted.
    3. Copy the token and store it somewhere safe—you will not be able to see it again.

    <Warning>
      Never share your bot token publicly or commit it to version control. Anyone with access to this token can control your bot.
    </Warning>
  </Step>

  <Step title="Invite the bot to your server">
    Now, invite the bot to your Discord server:

    1. In the left sidebar, select **OAuth2** > **OAuth2 URL Generator**.
    2. Under **Scopes**, select:
       * `bot`
       * `applications.commands`
    3. Under **Bot Permissions**, select the permissions your bot requires. At minimum:
       * **View Channels**
       * **Send Messages**
       * **Create Public Threads**
       * **Create Private Threads**
       * **Send Messages in Threads**
       * **Pin Messages**
       * **Attach Files**
       * **Read Message History**
       * **Add Reactions**
       * **Create Polls**
    4. Copy the generated URL at the bottom of the page and open it in your browser.
    5. Select the server you want to add the bot to and select **Authorize**.
  </Step>

  <Step title="Configure the integration in Botpress">
    In your Botpress integration configuration, click "Connect with OAuth", then follow the instructions in the wizard to fill out the following fields:

    1. In the integration's **Bot Token** field, paste your Discord bot token.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Discord integration is ready—users can now chat with your Botpress bot in Discord servers, threads, and direct messages.
</Check>

***

## Options

The Discord integration's **Configuration** menu offers a few additional options:

### Custom display name / avatar

* Fill in the **Bot Name** field to display a custom name as the sender in Discord conversations.
* Fill in the **Bot Avatar URL** field to set a custom image as the bot's Discord avatar.

<Note>
  The avatar URL must be publicly accessible. Supported formats include PNG, JPG, and GIF.
</Note>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add Member Role

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Add Reaction

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Ban User

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Call API

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="queryParams" type="array">
      <Expandable title="array item properties">
        <ResponseField name="key" type="string" />

        <ResponseField name="value" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="method" type="enum<string>">
      Available options: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
    </ResponseField>
  </Expandable>
</ResponseField>

### Create Channel

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="parentId" type="string | null" />

    <ResponseField name="topic" type="string | null" />
  </Expandable>
</ResponseField>

### Create Poll

### Create Role

### Delete Channel

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Reaction

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Role

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### End Poll

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="poll" type="object | null" />
  </Expandable>
</ResponseField>

### Get Channel Pins

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="messages" type="array">
      <Expandable title="array item properties">
        <ResponseField name="guildId" type="string | null" />

        <ResponseField name="author" type="object">
          <Expandable>
            <ResponseField name="globalName" type="string | null" />

            <ResponseField name="avatar" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="content" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Guild

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="icon" type="string | null" />

    <ResponseField name="description" type="string | null" />

    <ResponseField name="splash" type="string | null" />

    <ResponseField name="discoverySplash" type="string | null" />

    <ResponseField name="banner" type="string | null" />

    <ResponseField name="region" type="string | null" />

    <ResponseField name="afkChannelId" type="string | null" />

    <ResponseField name="maxPresences" type="number | null" />

    <ResponseField name="vanityUrlCode" type="string | null" />

    <ResponseField name="systemChannelId" type="string | null" />

    <ResponseField name="rulesChannelId" type="string | null" />

    <ResponseField name="publicUpdatesChannelId" type="string | null" />

    <ResponseField name="safetyAlertsChannelId" type="string | null" />
  </Expandable>
</ResponseField>

### Get Guild Channels

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="channels" type="array">
      <Expandable title="array item properties">
        <ResponseField name="parentId" type="string | null" />

        <ResponseField name="topic" type="string | null" />

        <ResponseField name="lastMessageId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Guild Member

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="user" type="object">
      <Expandable>
        <ResponseField name="globalName" type="string | null" />

        <ResponseField name="avatar" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="nick" type="string | null" />

    <ResponseField name="avatar" type="string | null" />
  </Expandable>
</ResponseField>

### getOrCreateChannelConversation

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="conversation" type="object">
      <Expandable>
        <ResponseField name="channelType" type="enum<string>">
          Available options: `dm`, `guildText`, `guildAnnouncement`, `announcementThread`, `publicThread`, `privateThread`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get or Create a User

### List Guild Members

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="members" type="array">
      <Expandable title="array item properties">
        <ResponseField name="user" type="object">
          <Expandable>
            <ResponseField name="globalName" type="string | null" />

            <ResponseField name="avatar" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="nick" type="string | null" />

        <ResponseField name="avatar" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Pin Message

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Remove Member Role

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Unban User

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Unpin Message

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>


# GitHub
Source: https://botpress.com/docs/integrations/integration-guides/github

Add a bot to GitHub using the official integration.

<OpenInHub />

The official GitHub integration allows your bot to interact with your GitHub repositories.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [GitHub account](https://github.com/signup)
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **GitHub** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize GitHub**.
      </Step>

      <Step>
        Follow the instructions to connect Botpress to your GitHub account.
      </Step>
    </Steps>

    <Note>
      When using this configuration mode, a Botpress-managed GitHub App connects to your GitHub organizations and repositories. The app has the necessary permissions to listen to pull request and issue events and to create comments on issues, pull requests, and discussions.

      If you need more granular control over permissions or prefer to use your own GitHub App, choose one of the manual configuration options instead.
    </Note>
  </Tab>

  <Tab title="Manual with GitHub App">
    For advanced use cases, you can use your own GitHub App with our integration.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [GitHub account](https://github.com/signup)
    </Info>

    ### Step 1: Install the integration

    First, install the integration in Botpress:

    <Steps>
      <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
      <Step>Search for the **GitHub** integration, then select **Install Integration**.</Step>
      <Step>In the **Configuration** menu, select the drop-down menu, then select **Configure with a GitHub App**.</Step>
      <Step>Copy the webhook URL—you'll need it when creating your GitHub App.</Step>
    </Steps>

    ### Step 2: Create a GitHub App

    Next, create your GitHub App:

    <Steps>
      <Step>On GitHub, navigate to your organization's **Settings** page (or your personal account settings).</Step>
      <Step>In the left sidebar, select **Developer settings**, then **GitHub Apps**.</Step>
      <Step>Select **New GitHub App**.</Step>

      <Step>
        Fill in the required fields:

        * **GitHub App name**: Choose a unique name for your app.
        * **Homepage URL**: Enter your organization's website or any valid URL.
      </Step>

      <Step>
        In the **Webhook** section:

        * Paste the webhook URL you copied from Botpress into the **Webhook URL** field.
        * Generate a secure secret key using a password generator.
        * Paste the secret key into the **Webhook secret** field.
      </Step>
    </Steps>

    ### Step 3: Configure permissions

    Set the required permissions for your GitHub App:

    **Repository permissions:**

    * **Discussions**: Read & write
    * **Issues**: Read & write
    * **Pull requests**: Read & write

    **Organization permissions:**

    * **Team discussions**: Read & write

    ### Step 4: Subscribe to webhook events

    Select the webhook events your bot should receive:

    * Discussion
    * Discussion comment
    * Issues
    * Issue comment
    * Pull request
    * Pull request review
    * Pull request review comment
    * Pull request review thread

    When you're done, select **Create GitHub App**.

    ### Step 5: Generate a private key

    Next, generate a private key:

    <Steps>
      <Step>In your newly created GitHub App, navigate to the **General** tab.</Step>
      <Step>Scroll down to **Private keys** and select **Generate a private key**.</Step>
      <Step>Save the downloaded `.pem` file to a secure location.</Step>
    </Steps>

    ### Step 6: Install the GitHub App

    Now you can install the GitHub App:

    <Steps>
      <Step>In your GitHub App's settings, select **Install App** from the left sidebar.</Step>
      <Step>Select the organization or account where you want to install the app.</Step>
      <Step>Choose whether to grant access to all repositories or select specific ones.</Step>
      <Step>Select **Install**.</Step>
    </Steps>

    ### Step 7: Configure the integration in Botpress

    Finally, fill in the integration's configuration fields:

    <AccordionGroup>
      <Accordion title="GitHub App ID">
        1. In your GitHub App's **General** tab, find the **App ID** field.
        2. Copy the App ID and paste it into the **GitHub App ID** field in Botpress.
      </Accordion>

      <Accordion title="GitHub App Private Key">
        Open the `.pem` file you downloaded earlier and paste its entire contents into the **GitHub App Private Key** field.
      </Accordion>

      <Accordion title="GitHub Webhook Secret">
        Paste the webhook secret key you generated in [Step 2](#step-2:-create-a-github-app) into the **GitHub Webhook Secret** field.
      </Accordion>

      <Accordion title="GitHub App Installation ID">
        1. Navigate to your organization's **Settings > Installed GitHub Apps**.
        2. Find your newly installed GitHub App and select **Configure**.
        3. Look at the URL—it should end with `/installations/:installation_id`. For example, in `https://github.com/organizations/my-org/settings/installations/123456`, the installation ID is `123456`.
        4. Copy the installation ID and paste it into the **GitHub App Installation ID** field in Botpress.
      </Accordion>
    </AccordionGroup>

    When you've filled in all the fields, select **Save Configuration**. This will automatically enable your integration.

    <Check>
      You've manually configured your GitHub integration with a GitHub App!
    </Check>
  </Tab>

  <Tab title="Manual with Personal Access Token (PAT)">
    You can also use a Personal Access Token (PAT) to connect your GitHub account to Botpress.

    <Warning>
      When you use a PAT, actions taken by the bot will be attributed to your personal GitHub account. If you want actions attributed to your organization, use the [GitHub App configuration](#manual-with-github-app) instead.

      GitHub Apps also don't consume a seat in your organization and offer more granular permissions—we recommend using them for production use cases.
    </Warning>

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [GitHub account](https://github.com/signup)
    </Info>

    ### Step 1: Install the integration

    <Steps>
      <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
      <Step>Search for the **GitHub** integration, then select **Install Integration**.</Step>
      <Step>In the **Configuration** menu, select the drop-down menu, then select **Configure with a Personal Access Token**.</Step>
      <Step>Copy the webhook URL—you'll need it when setting up the webhook.</Step>
    </Steps>

    ### Step 2: Enable fine-grained PATs for your organization

    If you're using an organization, you need to enable fine-grained Personal Access Tokens:

    <Steps>
      <Step>On GitHub, navigate to your organization's **Settings** page.</Step>
      <Step>In the left sidebar, under **Third-party Access**, select **Personal access tokens**.</Step>
      <Step>Select **Allow access via fine-grained personal access tokens**.</Step>
      <Step>Complete the setup process to enable fine-grained PATs.</Step>
    </Steps>

    <Note>
      You don't need to enable classic personal access tokens.
    </Note>

    ### Step 3: Set up the webhook

    <Steps>
      <Step>Navigate to either your repository or organization's **Settings** page on GitHub.</Step>
      <Step>In the left sidebar, select **Webhooks**, then **Add webhook**.</Step>

      <Step>
        Configure the webhook:

        * **Payload URL**: Paste the webhook URL from Botpress.
        * **Content type**: Select `application/json`.
        * **Secret**: Generate a secure secret key and paste it here.
      </Step>

      <Step>
        Under **Which events would you like to trigger this webhook?**, select **Let me select individual events**, then choose:

        * Discussion
        * Discussion comment
        * Issues
        * Issue comment
        * Pull request
        * Pull request review
        * Pull request review comment
        * Pull request review thread
      </Step>

      <Step>Select **Add webhook**.</Step>
    </Steps>

    ### Step 4: Create a fine-grained Personal Access Token

    <Steps>
      <Step>On GitHub, go to your account **Settings**.</Step>
      <Step>In the left sidebar, select **Developer settings**, then **Personal access tokens > Fine-grained tokens**.</Step>
      <Step>Select **Generate new token**.</Step>

      <Step>
        Configure the token:

        * **Token name**: Enter a descriptive name (e.g., "Botpress Integration").
        * **Expiration**: Choose an appropriate expiration date.
        * **Resource owner**: Select your organization (or personal account).
        * **Repository access**: Select the repositories your bot needs access to.

        <Note>
          If you select **Public Repositories only**, the bot won't be able to reply to issues or pull requests.
        </Note>
      </Step>

      <Step>
        Under **Permissions**, set the following:

        **Repository permissions:**

        * **Discussions**: Read & write
        * **Issues**: Read & write
        * **Pull requests**: Read & write

        **Organization (or Account) permissions:**

        * **Team discussions**: Read & write
      </Step>

      <Step>Select **Generate token** and copy it to a secure location.</Step>
    </Steps>

    ### Step 5: Configure the integration in Botpress

    Fill in the integration's configuration fields:

    <AccordionGroup>
      <Accordion title="GitHub Personal Access Token">
        Paste the Personal Access Token you generated in the previous step.
      </Accordion>

      <Accordion title="GitHub Webhook Secret">
        Paste the webhook secret key you generated in [Step 3](#step-3:-set-up-the-webhook).
      </Accordion>
    </AccordionGroup>

    When you've filled in all the fields, select **Save Configuration**. This will automatically enable your integration.

    <Check>
      You've manually configured your GitHub integration with a Personal Access Token!
    </Check>
  </Tab>
</Tabs>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Find Target

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="channel" type="enum<string>">
      Available options: `pullRequest`, `issue`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="targets" type="array">
      <Expandable title="array item properties">
        <ResponseField name="channel" type="enum<string>">
          Available options: `pullRequest`, `issue`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Aggregate File Changes

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="modifiedItems" type="object">
      <Expandable>
        <ResponseField name="created" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="updated" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="deleted" type="array">
          <Tabs>
            <Tab title="file">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>

            <Tab title="folder">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>
          </Tabs>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Created

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Deleted

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Folder Deleted Recursive

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="folder" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Issue opened

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="content" type="string | null" />
  </Expandable>
</ResponseField>

### Pull Request merged

### Pull Request opened

### Pull Request review submitted

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="review" type="object">
      <Expandable>
        <ResponseField name="state" type="enum<string>">
          Available options: `APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `DISMISSED`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Gmail
Source: https://botpress.com/docs/integrations/integration-guides/gmail



<OpenInHub />

The Gmail integration allows your bot to chat with users via your Gmail address.

<Danger>
  Once you've successfully configured the Gmail integration, **the email address you provided will begin responding to all incoming emails as your bot**. Please be aware of this behaviour before configuring the integration.
</Danger>

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Google account](https://accounts.google.com/)
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Gmail** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize Gmail**.
      </Step>

      <Step>
        Follow the instructions to connect Botpress to your Google account.
      </Step>
    </Steps>

    <Note>
      When using basic configuration, a Botpress-managed Gmail application will be used to connect to your Gmail account. However, actions taken by the bot will be attributed to the user who authorized the connection rather than the application.

      For this reason, **we don't recommend using personal Gmail accounts** for this integration. You should set up a [service account](https://docs.cloud.google.com/iam/docs/service-account-overview) and use that account to authorize the connection.
    </Note>
  </Tab>

  <Tab title="Manual configuration">
    For more advanced use cases, you can manually configure the integration.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Google account](https://accounts.google.com/)
      * Access to [Google Cloud Console](https://console.cloud.google.com/)
    </Info>

    ### Step 1. Create a Google Cloud Platform project

    <Steps>
      <Step>
        Log in to [Google Cloud Console](https://console.cloud.google.com/) with your Gmail account.
      </Step>

      <Step>
        Select **Select a project** dropdown in the top navigation. Then, select **New Project**.
      </Step>

      <Step>
        Follow the on-screen instructions to create the new project.
      </Step>
    </Steps>

    ### Step 2. Enable the Gmail API

    <Steps>
      <Step>
        In Google Cloud Console, navigate to the **APIs & Services** section.
      </Step>

      <Step>
        Select **Library** from the left sidebar.
      </Step>

      <Step>
        Search for **Gmail API** and select the result.
      </Step>

      <Step>
        Select **Enable** to enable the Gmail API for your project.
      </Step>
    </Steps>

    ### Step 3. Configure the OAuth consent screen

    <Steps>
      <Step>
        In Google Cloud Console, navigate to the **APIs & Services** section.
      </Step>

      <Step>
        Select **OAuth consent screen** in the left sidebar.
      </Step>

      <Step>
        Select **Get Started** and fill out the **App Information** section. Then, select **Next**.
      </Step>

      <Step>
        Under **Audience**, select **External**.
      </Step>

      <Step>
        Fill in the other required sections, then select **Create**.
      </Step>

      <Step>
        Navigate to the **Data Access** tab, then select **Add or remove scopes**.
      </Step>

      <Step>
        Under **Manually add scopes**, enter the following:

        ```plaintext theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        https://www.googleapis.com/auth/userinfo.email
        https://www.googleapis.com/auth/userinfo.profile
        https://mail.google.com/
        https://www.googleapis.com/auth/gmail.send
        ```
      </Step>

      <Step>
        Select **Add to table**, then **Update**.
      </Step>

      <Step>
        Select **Save** at the bottom of the screen.
      </Step>

      <Step>
        Navigate to the **Audience** tab. Under **Test users**, select **+ Add users**.
      </Step>

      <Step>
        Add an email address for testing the app, then select **Save**.
      </Step>
    </Steps>

    ### Step 4. Create OAuth credentials

    <Steps>
      <Step>
        In Google Cloud Console, navigate to the **APIs & Services** section.
      </Step>

      <Step>
        Select **Credentials** in the left sidebar.
      </Step>

      <Step>
        Select **Create credentials**, then **OAuth client ID**.
      </Step>

      <Step>
        Select **Web application** as the application type.
      </Step>

      <Step>
        Enter a name for the OAuth client ID.
      </Step>

      <Step>
        Under **Authorized redirect URIs**, enter `https://botpress.com`.
      </Step>

      <Step>
        Select **Add URI**, then **Create**.
      </Step>

      <Step>
        Copy the **Client ID** and **Client secret** for use in the next steps.

        <Note>
          The client ID is the string that ends with `.apps.googleusercontent.com`.
        </Note>
      </Step>
    </Steps>

    ### Step 5. Create a service account

    <Steps>
      <Step>
        In Google Cloud Console, navigate to the **IAM & Admin** section.
      </Step>

      <Step>
        Select **Service accounts** in the left sidebar.
      </Step>

      <Step>
        Select **Create service account**.
      </Step>

      <Step>
        Enter a name for the service account. Then, select **Done**.

        <Note>
          You don't need to grant any roles to the service account, as it will only be used to sign webhook events.
        </Note>
      </Step>

      <Step>
        Copy the service account email address for use in the next steps.

        <Tip>
          The service account email address is the string that ends with `.gserviceaccount.com`.
        </Tip>
      </Step>
    </Steps>

    ### Step 6. Create a Pub/Sub topic

    <Steps>
      <Step>
        In Google Cloud Console, search for and navigate to the **Pub/Sub** section.
      </Step>

      <Step>
        Select **Topics** in the left sidebar.
      </Step>

      <Step>
        Select **Create topic**.
      </Step>

      <Step>
        Enter a name for the topic in the **Topic ID** field.
      </Step>

      <Step>
        Uncheck the **Add default subscription** checkbox. Leave the other options unchanged.
      </Step>

      <Step>
        Select **Create** to create the topic.
      </Step>

      <Step>
        Copy the **Topic name** for use in the next steps.

        <Note>
          The topic name is the string that starts with `projects/`.
        </Note>
      </Step>
    </Steps>

    ### Step 7. Grant publish rights on the Pub/Sub topic

    <Steps>
      <Step>
        In Google Cloud Console, search for and navigate to the **Pub/Sub** section.
      </Step>

      <Step>
        Select **Topics** in the left sidebar.
      </Step>

      <Step>
        From the topic list, find the topic you created earlier. Then, select the triple-dot <kbd>⋮</kbd> button on the right.
      </Step>

      <Step>
        Select **View permissions** from the dropdown menu.
      </Step>

      <Step>
        Select **Add principal**.
      </Step>

      <Step>
        Under **Add principals**, enter `gmail-api-push@system.gserviceaccount.com`.

        <Note>
          This service account is managed by Google and is used to push events to Pub/Sub.
        </Note>
      </Step>

      <Step>
        Under **Assign roles**, select `Pub/Sub Publisher`.
      </Step>

      <Step>
        Select **Save** to grant publish rights to the service account.
      </Step>
    </Steps>

    ### Step 8. Generate a shared secret

    <Steps>
      <Step>
        Generate an alphanumeric string to use as a shared secret for signing Pub/Sub push events. We recommend using a string with at least 32 characters.

        <Tip>
          You can use an [online password generator](https://bitwarden.com/password-generator/) to create a secure string.
        </Tip>
      </Step>

      <Step>
        Copy this string for use in the next steps.
      </Step>
    </Steps>

    ### Step 9. Create a Pub/Sub subscription

    <Steps>
      <Step>
        In Google Cloud Console, search for and navigate to the **Pub/Sub** section.
      </Step>

      <Step>
        Select **Subscriptions** in the left sidebar.
      </Step>

      <Step>
        Select **Create subscription**.
      </Step>

      <Step>
        Enter a name for the subscription in the **Subscription ID** field.
      </Step>

      <Step>
        Select the topic you created earlier from the topic dropdown.
      </Step>

      <Step>
        Under **Delivery type**, select **Push**.
      </Step>

      <Step>
        Enter your integration's Botpress-provided webhook URL in the **Endpoint URL** field. To this URL, add `?shared_secret=`, followed by the shared secret you generated earlier.

        <Tip>
          For example, if:

          * Your integration's webhook URL is: `https://webhook.botpress.cloud/57fcfb04-51fd-4381-909a-10e6ae53d310`
          * Your shared secret is `Ut5hzrxs7uV87mzCAKL3ztrzesWWBiNa`

          You would enter:

          `https://webhook.botpress.cloud/57fcfb04-51fd-4381-909a-10e6ae53d310?shared_secret=Ut5hzrxs7uV87mzCAKL3ztrzesWWBiNa`

          in the **Endpoint URL** field.
        </Tip>
      </Step>

      <Step>
        Check the **Enable authentication** checkbox.
      </Step>

      <Step>
        Select the service account email address you created earlier in the **Service account** field.
      </Step>

      <Step>
        Enter the shared secret you generated earlier in the **Audience** field.

        <Note>
          Although this field is marked optional in Google Console, it's required for the integration to work properly.
        </Note>
      </Step>

      <Step>
        Under **Expiration period**, select **Never expire**.
      </Step>

      <Step>
        Under **Acknowledgement deadline**, enter 60 seconds.
      </Step>

      <Step>
        Under **Retry policy**, select **Retry after exponential backoff delay**. Set the minimum backoff to 60 seconds and the maximum backoff to 600 seconds.
      </Step>

      <Step>
        Select **Create** to create the subscription.
      </Step>
    </Steps>

    ### Step 10. Authorize the OAuth application

    <Steps>
      <Step>
        On Gmail, log in to the Google account you want to use with the Gmail integration.
      </Step>

      <Step>
        Once logged in, go to the following URL in your browser:

        ```
        https://accounts.google.com/o/oauth2/auth?response_type=code&scope=https://mail.google.com/%20https://www.googleapis.com/auth/gmail.send&access_type=offline&prompt=consent&redirect_uri=https://botpress.com&client_id=YOUR_CLIENT_ID
        ```

        Replace `YOUR_CLIENT_ID` with your OAuth **Client ID** from [Step 4](#step-4-create-oauth-credentials). For example, if your OAuth client ID is `abcd`, the URL should end with `&client_id=abcd`.
      </Step>

      <Step>
        Follow the on-screen instructions to authorize the OAuth application with your personal Gmail account.

        <Warning>
          After completing the authorization, you will be redirected to [botpress.com](https://botpress.com). Don't close this page.
        </Warning>
      </Step>

      <Step>
        Copy the **authorization code** from the URL in your browser's address bar. The authorization code is the string that appears after `code=` and before `&scope=` in the URL.

        <Tip>
          If you have difficulty finding the authorization code in the URL, you can use online tools like [https://semalt.tools/en/url-parser](https://semalt.tools/en/url-parser) or [https://parseurlonline.com](https://parseurlonline.com).
        </Tip>

        <Note>
          If you update any scopes, you need to generate a new authorization code and add it to the integration's configuration in Botpress Studio. The previous authorization code won't have the correct scope permissions.
        </Note>
      </Step>

      <Step>
        You can now safely close this page.
      </Step>
    </Steps>

    ### Step 11. Configure the integration in Botpress

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Gmail** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Configure manually with your own GCP App**.
      </Step>

      <Step>
        Fill in the required fields with all the information you saved from the previous steps.

        <Warning>
          The authorization code is only valid for a short period of time. If the code has expired, you will need to repeat the steps outlined in [Step 10](#step-10-authorize-the-oauth-application).
        </Warning>
      </Step>

      <Step>
        Select **Save Configuration**. If no error message is displayed, the integration was successfully configured.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Using the integration

Once you’ve successfully configured the integration, the email address you provided will begin responding to all incoming messages as your bot. If this is your desired behaviour, no additional setup is required.

You can also use the integration's [Cards](#cards) to interact with your Gmail inbox. This allows you to manage threads, drafts, attachments, and other data associated with your inbox.

***

## Limitations

<AccordionGroup>
  <Accordion title="Costs">
    Botpress shall not be held responsible for any costs you may incur on the Google Cloud Platform while using the Gmail integration, should you choose to use the manual configuration mode. Ensure that you are aware of the costs associated with using the Gmail API and the Google Cloud Platform before using the manual configuration mode.
  </Accordion>

  <Accordion title="API limits">
    Standard Gmail API limitations apply to the Gmail integration in Botpress. These limitations include rate limits, message size restrictions, and other constraints imposed by the Gmail and Google Cloud platforms. Ensure that your bot adheres to these limitations to maintain optimal performance and reliability.

    More details are available in the [Gmail API documentation](https://developers.google.com/gmail/api/reference/quota).
  </Accordion>
</AccordionGroup>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Change Message Labels

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Create Draft

### Create Label

### Delete Draft

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Label

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Message

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Get Draft

### Get Label

### Get Message Attachment

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="attachment" type="object">
      <Expandable>
        <ResponseField name="size" type="number | null" />

        <ResponseField name="data" type="string | null" />

        <ResponseField name="attachmentId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Message Attachment From Mail

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="attachment" type="object">
      <Expandable>
        <ResponseField name="size" type="number | null" />

        <ResponseField name="data" type="string | null" />

        <ResponseField name="attachmentId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Thread

### List Drafts

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### List Labels

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### List Threads

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### Send Draft

### Trash Message

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Trash Thread

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Untrash Message

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Untrash Thread

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Update Draft

### Update Label


# Google Calendar
Source: https://botpress.com/docs/integrations/integration-guides/googlecalendar

Add a bot to Google Calendar using the official integration.

<OpenInHub />

The official Google Calendar integration allows your bot to access your Google Calendar data and manage events.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Google account](https://www.google.com/url?sa=t\&source=web\&rct=j\&opi=89978449\&url=https://accounts.google.ca/\&ved=2ahUKEwjT06jO35CSAxWy5MkDHcRzEJIQFnoECAwQAQ\&usg=AOvVaw2kpHPlQsXrFmVVEu4DOt-N)
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Google Calendar** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize Google Calendar**.
      </Step>

      <Step>
        Follow the instructions to connect Botpress to your Google account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual configuration">
    For more advanced use cases, you can manually configure the integration.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Google account](https://accounts.google.com/signup)
      * Access to [Google Cloud Console](https://console.developers.google.com/)
    </Info>

    ### Step 1: Create a Google Cloud project

    <Steps>
      <Step>
        Go to the [Google Cloud Console](https://console.developers.google.com/) and sign in with your Google account.
      </Step>

      <Step>
        Go to **Select a project**, then select **New Project**.
      </Step>

      <Step>
        Enter your project details:

        * **Project name**: Choose a descriptive name for your project.
        * **Organization**: Select your organization (if applicable).
        * **Location**: Choose the appropriate location.
      </Step>

      <Step>
        Select **Create** and wait for the project to be created.
      </Step>

      <Step>
        Verify you're in the correct project by checking the project name next to the Google logo.
      </Step>
    </Steps>

    ### Step 2: Enable the Google Calendar API

    <Steps>
      <Step>
        In the Google Cloud Console, open the left sidebar and go to **API & Services > Credentials**.
      </Step>

      <Step>
        Select **+ Create Credentials > API Key** to create an API key. Copy and store it somewhere.
      </Step>

      <Step>
        Go to **Library**, search for "Google Calendar API", and select **Enable**.
      </Step>
    </Steps>

    ### Step 3: Create a service account

    <Steps>
      <Step>
        Open the left sidebar again and go to **API & Services > Credentials**.
      </Step>

      <Step>
        Select **+ Create Credentials > Service Account**.
      </Step>

      <Step>
        Enter a **Service account name**. The Service Account ID will be automatically generated.
      </Step>

      <Step>
        The remaining fields are optional. Select **Done** to create the service account.
      </Step>

      <Step>
        Select your newly created service account, then go to the **Keys** tab.
      </Step>

      <Step>
        Select **Add Key > Create new key**, choose **JSON** as the key type, then select **Create**.

        A JSON file will be downloaded to your machine. Keep this file secure—you'll need it to configure the integration.
      </Step>
    </Steps>

    <Note>
      The downloaded JSON file contains sensitive credentials. Store it securely and never share it publicly. The file structure looks like this:

      ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "...",
        "private_key": "...",
        "client_email": "your-service-account@your-project.iam.gserviceaccount.com",
        "client_id": "...",
        "auth_uri": "...",
        "token_uri": "...",
        "auth_provider_x509_cert_url": "...",
        "client_x509_cert_url": "...",
        "universe_domain": "googleapis.com"
      }
      ```
    </Note>

    ### Step 4: Enable domain-wide delegation (Google Workspace only)

    <Warning>
      Domain-wide delegation is **required** if you want your bot to:

      * Create Google Meet links for events
      * Send invitations to attendees
      * Act on behalf of users in your organization

      Without domain-wide delegation, the service account can only manage its own calendar and cannot invite attendees or create Meet links.

      **This feature is only available for Google Workspace accounts.** Personal `@gmail.com` accounts do not support domain-wide delegation.
    </Warning>

    Follow Google's official guide to [delegate domain-wide authority to your service account](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority).

    When configuring the OAuth scopes in the Google Admin Console, paste in the following scopes (comma-separated):

    ```
    https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.events
    ```

    ### Step 5: Configure OAuth consent screen (if not already configured)

    <Steps>
      <Step>
        Open the left sidebar again and go to **API & Services > OAuth consent screen**.
      </Step>

      <Step>
        Select **Get started**.
      </Step>

      <Step>
        Configure the OAuth consent screen. Under **App Information**:

        * **App name**: Enter a name for your application.
        * **User support email**: Select your email address.

        Then, select **Next**.
      </Step>

      <Step>
        Under **Audience**, select **Internal**. Then, select **Next**.
      </Step>

      <Step>
        Under **Contact Information**, enter a contact email address. Then, select **Next**.
      </Step>

      <Step>
        Agree to the Google API policy, then select **Create**.
      </Step>
    </Steps>

    ### Step 6: Create OAuth client

    <Steps>
      <Step>
        Select **Create OAuth client**.
      </Step>

      <Step>
        Select an **Application type** and enter a name. Then select **Create**.
      </Step>
    </Steps>

    ### Step 7: Configure scopes

    <Steps>
      <Step>
        Go to **Data Access** in the left sidebar, then select **Add or remove scopes**.
      </Step>

      <Step>
        Add the following scopes:

        * `https://www.googleapis.com/auth/calendar`
        * `https://www.googleapis.com/auth/calendar.events`
      </Step>

      <Step>
        Select **Update**.
      </Step>
    </Steps>

    ### Step 8: Grant calendar access to the service account

    <Steps>
      <Step>
        Open [Google Calendar](https://calendar.google.com) and select the settings icon in the upper-right corner. Then, select **Settings**.
      </Step>

      <Step>
        In the left sidebar, select the calendar you want to share with your bot.
      </Step>

      <Step>
        Go to **Shared with** > **+ Add people and groups**.
      </Step>

      <Step>
        Enter the `client_email` from your downloaded JSON file (for example, `your-service-account@your-project.iam.gserviceaccount.com`).
      </Step>

      <Step>
        Set the permission to **Make changes to events** so the bot can manage calendar events.
      </Step>
    </Steps>

    ### Step 9: Configure the integration in Botpress

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Google Calendar** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select the drop-down and choose **Configure manually**.
      </Step>
    </Steps>

    Fill in the integration's configuration fields:

    <AccordionGroup>
      <Accordion title="Calendar ID">
        1. In Google Calendar, go to **Settings** and select your calendar.
        2. Scroll to **Integrate calendar** to find your Calendar ID.
        3. Copy the Calendar ID and paste it into the **Calendar ID** field in Botpress.
      </Accordion>

      <Accordion title="Client Email">
        Open the JSON file you downloaded in [Step 3](#step-3-create-a-service-account) and copy the `client_email` value.
      </Accordion>

      <Accordion title="Private Key">
        Open the JSON file you downloaded in [Step 3](#step-3-create-a-service-account) and copy the entire `private_key` value, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` markers.
      </Accordion>

      <Accordion title="Impersonate Email (Google Workspace only)">
        Enter the email address of a user in your Google Workspace that the service account will impersonate.

        This field is **required** for:

        * Creating Google Meet links
        * Sending attendee invitations

        The email must belong to an actual user in your Google Workspace domain. Without this field configured, Meet creation and attendee invitations will not work.

        <Note>
          This field only applies if you have configured [domain-wide delegation](#step-4-enable-domain-wide-delegation-google-workspace-only). Personal @gmail.com accounts do not support impersonation.
        </Note>
      </Accordion>
    </AccordionGroup>

    When you've filled in all the fields, select **Save Configuration**.

    <Check>
      You've successfully configured the Google Calendar integration!
    </Check>
  </Tab>
</Tabs>

***

## Limitations

Different Google account types have different capabilities when using this integration.

| Feature                             |                                             Google Workspace                                            | Personal (`@gmail.com`) |
| ----------------------------------- | :-----------------------------------------------------------------------------------------------------: | :---------------------: |
| Create, read, update, delete events |                                                   Yes                                                   |           Yes           |
| Create Google Meet links            |                                                   Yes                                                   |            No           |
| Invite attendees                    | Yes ([requires domain-wide delegation](#step-4%3A-enable-domain-wide-delegation-google-workspace-only)) |            No           |

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Check Availability

### Create Event

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="status" type="enum<string>">
      Available options: `confirmed`, `tentative`, `cancelled`
    </ResponseField>

    <ResponseField name="visibility" type="enum<string>">
      Available options: `default`, `public`, `private`, `confidential`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="eventType" type="enum<string>">
      Available options: `default`, `birthday`, `focusTime`, `fromGmail`, `outOfOffice`, `workingLocation`
    </ResponseField>

    <ResponseField name="status" type="enum<string>">
      Available options: `confirmed`, `tentative`, `cancelled`
    </ResponseField>

    <ResponseField name="visibility" type="enum<string>">
      Available options: `default`, `public`, `private`, `confidential`
    </ResponseField>

    <ResponseField name="attendees" type="array">
      <Expandable title="array item properties">
        <ResponseField name="responseStatus" type="enum<string>">
          Available options: `needsAction`, `declined`, `tentative`, `accepted`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Delete Event

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### List Events

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="events" type="array">
      <Expandable title="array item properties">
        <ResponseField name="eventType" type="enum<string>">
          Available options: `default`, `birthday`, `focusTime`, `fromGmail`, `outOfOffice`, `workingLocation`
        </ResponseField>

        <ResponseField name="status" type="enum<string>">
          Available options: `confirmed`, `tentative`, `cancelled`
        </ResponseField>

        <ResponseField name="visibility" type="enum<string>">
          Available options: `default`, `public`, `private`, `confidential`
        </ResponseField>

        <ResponseField name="attendees" type="array">
          <Expandable title="array item properties">
            <ResponseField name="responseStatus" type="enum<string>">
              Available options: `needsAction`, `declined`, `tentative`, `accepted`
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Update Event

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="status" type="enum<string>">
      Available options: `confirmed`, `tentative`, `cancelled`
    </ResponseField>

    <ResponseField name="visibility" type="enum<string>">
      Available options: `default`, `public`, `private`, `confidential`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="eventType" type="enum<string>">
      Available options: `default`, `birthday`, `focusTime`, `fromGmail`, `outOfOffice`, `workingLocation`
    </ResponseField>

    <ResponseField name="status" type="enum<string>">
      Available options: `confirmed`, `tentative`, `cancelled`
    </ResponseField>

    <ResponseField name="visibility" type="enum<string>">
      Available options: `default`, `public`, `private`, `confidential`
    </ResponseField>

    <ResponseField name="attendees" type="array">
      <Expandable title="array item properties">
        <ResponseField name="responseStatus" type="enum<string>">
          Available options: `needsAction`, `declined`, `tentative`, `accepted`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Event Created

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="item" type="string" />
  </Expandable>
</ResponseField>

### Event Deleted

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="id" type="string" />
  </Expandable>
</ResponseField>

### Event Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="item" type="string" />
  </Expandable>
</ResponseField>


# Google Sheets
Source: https://botpress.com/docs/integrations/integration-guides/gsheets

Add a bot to Google Sheets using the official integration.

<OpenInHub />

The Google Sheets integration allows your bot to access and update Google Sheets data in real-time, automating tasks like CRM updates, inventory management, and survey tracking directly within chat.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Google account](https://accounts.google.com/)
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Google Sheets** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize Google Sheets**.
      </Step>

      <Step>
        Follow the instructions to connect Botpress to your Google account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual configuration">
    For more advanced use cases, you can manually configure the integration using a service account.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Google account](https://accounts.google.com/)
      * Access to [Google Cloud Console](https://console.developers.google.com/)
    </Info>

    ### Step 1: Create a Google Cloud project

    <Steps>
      <Step>
        Go to the [Google Cloud Console](https://console.developers.google.com/) and sign in with your Google account.
      </Step>

      <Step>
        Open the project picker dropdown in the top navigation. Then, select **New Project**.
      </Step>

      <Step>
        Enter your project details:

        * **Project name**: Choose a descriptive name for your project.
        * **Organization**: Select your organization (if applicable).
        * **Location**: Choose the appropriate location.
      </Step>

      <Step>
        Select **Create** and wait for the project to be created.
      </Step>

      <Step>
        Verify you're in the correct project by checking the project name next to the Google logo.
      </Step>
    </Steps>

    ### Step 2: Enable the Google Sheets API

    <Steps>
      <Step>
        In the Google Cloud Console, open the left sidebar and go to **API & Services > Credentials**.
      </Step>

      <Step>
        Select **+ Create Credentials > API Key** to create an API key.
      </Step>

      <Step>
        Go to **Library**, search for "Google Sheets API", and select **Enable**.
      </Step>
    </Steps>

    ### Step 3: Create a service account

    <Steps>
      <Step>
        Open the left sidebar and go to **API & Services > Credentials**.
      </Step>

      <Step>
        Select **+ Create Credentials > Service Account**.
      </Step>

      <Step>
        Enter a **Service account name**. The Service Account ID will be automatically generated.
      </Step>

      <Step>
        The remaining fields are optional. Select **Done** to create the service account.
      </Step>

      <Step>
        Select your newly created service account, then go to the **Keys** tab.
      </Step>

      <Step>
        Select **Add Key > Create new key**, choose **JSON** as the key type, then select **Create**.

        A JSON file will be downloaded to your machine. Keep this file secure—you'll need it to configure the integration.
      </Step>
    </Steps>

    <Note>
      The downloaded JSON file contains sensitive credentials. Store it securely and never share it publicly. The file structure looks like this:

      ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "...",
        "private_key": "...",
        "client_email": "your-service-account@your-project.iam.gserviceaccount.com",
        "client_id": "...",
        "auth_uri": "...",
        "token_uri": "...",
        "auth_provider_x509_cert_url": "...",
        "client_x509_cert_url": "...",
        "universe_domain": "googleapis.com"
      }
      ```
    </Note>

    ### Step 4: Grant spreadsheet access to the service account

    <Steps>
      <Step>
        Open your Google Sheets spreadsheet in your browser.
      </Step>

      <Step>
        Select the **Share** button in the upper-right corner.
      </Step>

      <Step>
        Open the JSON file you downloaded and copy the `client_email` value.
      </Step>

      <Step>
        Paste the `client_email` into the **Add people and groups** field, as if you were inviting someone to access your spreadsheet.
      </Step>

      <Step>
        Set the permission to **Editor** so the bot can read and write to the spreadsheet. Then select **Send**.
      </Step>
    </Steps>

    ### Step 5: Configure the integration in Botpress

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Google Sheets** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select the drop-down and choose **Configure manually with a Service Account Key**.
      </Step>
    </Steps>

    Fill in the integration's configuration fields:

    <AccordionGroup>
      <Accordion title="Spreadsheet ID">
        1. Open your Google Sheets spreadsheet in your browser.
        2. Copy the ID from the URL. The ID is the string between `/d/` and `/edit` in the URL.

        For example, if your URL is `https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit`, the Spreadsheet ID is `1AbCdEfGhIjKlMnOpQrStUvWxYz`.
      </Accordion>

      <Accordion title="Client Email">
        Open the JSON file you downloaded in [Step 3](#step-3-create-a-service-account) and copy the `client_email` value.
      </Accordion>

      <Accordion title="Private Key">
        Open the JSON file you downloaded in [Step 3](#step-3-create-a-service-account) and copy the entire `private_key` value, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` markers.
      </Accordion>
    </AccordionGroup>

    When you've filled in all the fields, select **Save Configuration**.

    <Check>
      You've successfully configured the Google Sheets integration!
    </Check>
  </Tab>
</Tabs>

***

## Cards

<Note>
  For Cards that take [named ranges](https://support.google.com/docs/answer/63175?hl=en\&co=GENIE.Platform%3DDesktop) as input, Google's standard restrictions for range names apply. Range names:

  * Can contain only letters, numbers, and underscores
  * Can't start with a number, or the words "true" or "false"
  * Can't contain any spaces or punctuation
  * Must be 1–250 characters
  * Can't be in either A1 or R1C1 syntax. For example, you might get an error if you give your range a name like `A1:B2` or `R1C1:R2C2`
</Note>

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add Sheet

### Append Values

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="majorDimension" type="enum<string>">
      Available options: `ROWS`, `COLUMNS`
    </ResponseField>
  </Expandable>
</ResponseField>

### Clear Values

### Create Named Range in Sheet

### Delete Rows

### Delete Sheet

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Find Row (First Match)

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="row" type="object | null" />
  </Expandable>
</ResponseField>

### Find Rows

### Get All Sheets in Spreadsheet

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### Get Info of a SpreadSheet

### Get Named Ranges

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### Get Protected Ranges

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### Get Row

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="row" type="object | null" />
  </Expandable>
</ResponseField>

### Get Values

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="majorDimension" type="enum<string>">
      Available options: `ROWS`, `COLUMNS`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="majorDimension" type="enum<string>">
      Available options: `ROWS`, `COLUMNS`
    </ResponseField>
  </Expandable>
</ResponseField>

### Insert Row at Index

### Move Sheet Horizontally

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Protect Named Range

### Rename Sheet

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Set Sheet Visibility

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Set Values

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="majorDimension" type="enum<string>">
      Available options: `ROWS`, `COLUMNS`
    </ResponseField>
  </Expandable>
</ResponseField>

### Unprotect Range

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Update Row

### Upsert Row

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="action" type="enum<string>">
      Available options: `updated`, `inserted`
    </ResponseField>
  </Expandable>
</ResponseField>


# Human-in-the-Loop (HITL)
Source: https://botpress.com/docs/integrations/integration-guides/hitl/introduction

Allow a live agent to participate directly in the bot's conversation.

<OpenInHub />

<Warning>
  For new workspaces, HITL has moved to [Botpress Desk](https://botpress.com/desk), our new AI helpdesk for modern support teams. From your dashboard, go to <Icon icon="message-square-reply" /> **Human Handoff > Open Botpress Desk** to get started setting up your workspace.

  Users on existing workspaces can follow the steps below and continue using the legacy HITL integration.
</Warning>

The Human-in-the-Loop (HITL) integration allows members of your Workspace to:

* Chat directly with users
* Approve AI-generated outputs before they're sent
* Handle complex or sensitive scenarios

<Note>
  The HITL integration needs to be configured before you can use [Human Handoff](/docs/get-started/manage-your-agent/human-handoff).
</Note>

## Setup

<Info>
  You will need:

  * A [Botpress Plus plan](https://botpress.com/pricing) or higher
</Info>

### Step 1: Install the HITL integration

First, install the official HITL integration:

<Steps>
  <Step>
    In Botpress Studio, select **Explore Hub** in the upper-right corner.
  </Step>

  <Step>
    Search for the HITL integration, then select **Install Integration**.
  </Step>
</Steps>

### Step 2: Install the HITL plugin

Next, install the official HITL plugin. This will allow you to start HITL from any point in your Workflow.

<Steps>
  <Step>
    Navigate back to Botpress Hub and search for the HITL plugin.
  </Step>

  <Step>
    Select it, then select **Install Plugin**.
  </Step>

  <Step>
    In the **Configuration** menu, open the dropdown under **HITL integration**.

    <Note>
      This dropdown will display all HITL-compatible integrations you've installed. Since this is a guide to the official Botpress HITL integration, we'll select that one for now.
    </Note>
  </Step>

  Select **HITL**.

  <Step>
    Scroll down and select **Save**.
  </Step>
</Steps>

<Tip>
  The plugin's **Configuration** section contains many optional fields. You can use these to customize your HITL experience.
</Tip>

### Step 3: Add the Start HITL card to your Workflow

<Steps>
  <Step>
    Open a Workflow in Studio and create (or select) any Node.
  </Step>

  <Step>
    Add the **Start HITL** Card at the point where you want to hand off conversations to a live agent:

    <Frame>
      <img alt="Start HITL Card" />

      <img alt="Start HITL Card" />
    </Frame>
  </Step>

  <Step>
    In the Card's [inspector](/docs/studio/concepts/cards/introduction#configure-a-card), fill in the required fields:

    | Fields              | Description                                                                                                                         |
    | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
    | **Ticket Title**    | The name of the ticket created for the live agent.                                                                                  |
    | **User ID**         | The user ID associated with the ticket. Enter the `{{event.userId}}` variable to use the current user's ID.                         |
    | **Conversation ID** | The conversation ID associated with the ticket. Enter the `{{event.conversationId}}` variable to use the current conversation's ID. |
  </Step>
</Steps>

<Check>
  Done! HITL will begin whenever the **Start HITL** card executes.

  For more information about assigning live agents and managing conversations, check out the [Human Handoff](/docs/get-started/manage-your-agent/human-handoff) guide.
</Check>


# Measure HITL Response Time
Source: https://botpress.com/docs/integrations/integration-guides/hitl/time-to-first-agent-response

Measure the Time to First Agent Response for conversations in HITL.

## Prerequisites

<Info>
  You will need:

  * A [Botpress Plus plan](https://botpress.com/pricing) or higher
  * The [HITL integration and plugin configured](/docs/integrations/integration-guides/hitl/introduction) so agents can join conversations
</Info>

This guide explains how to measure the **Time to First Agent Response** for conversations handed off to a human agent via [Human-in-the-Loop (HITL)](/docs/integrations/integration-guides/hitl/introduction). The metric captures how long a user waited from the moment they requested a human agent to the moment an agent was assigned.

The result is stored as a formatted string in a conversation variable and can be sent using a [Text Card](/docs/studio/concepts/cards/send-messages#text), [sent to an external system](/docs/studio/concepts/cards/execute-code), or [saved to a Botpress table](/docs/studio/concepts/cards/tables#insert-record).

## 1. Create conversation variables

Create the following two variables in your bot, scoped as **Conversation** variables:

| Variable Name          | Type   | Description                                           |
| :--------------------- | :----- | :---------------------------------------------------- |
| `hitlRequestTimestamp` | number | Unix timestamp (ms) of when the HITL request was made |
| `hitlTimingDisplay`    | string | Formatted summary string of the timing result         |

In Botpress Studio, go to **Variables** → **+ New Variable**, set the scope to **Conversation**, and configure each entry as described above.

## 2. Capture the request timestamp

Before your [Start HITL](/docs/integrations/integration-guides/hitl/introduction#step-3-add-the-start-hitl-card-to-your-workflow) Card, insert an [Execute Code](/docs/studio/concepts/cards/execute-code) Card that records when the user was handed off to HITL. Use the following code:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
conversation.hitlRequestTimestamp = Date.now()
```

This stores the exact moment the user was handed off to HITL, in milliseconds since the [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time).

<Info title="Unix Epoch">
  The **Unix Epoch** is January 1, 1970 at 00:00:00 UTC. Timestamps in "milliseconds since the Unix epoch" are the number of milliseconds elapsed since that moment.
</Info>

## 3. Calculate and format the wait time

After your [Start HITL](/docs/integrations/integration-guides/hitl/introduction#step-3-add-the-start-hitl-card-to-your-workflow) Card, insert another [Execute Code](/docs/studio/concepts/cards/execute-code) Card that computes the time until an agent was assigned and formats the result. Use the following code:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { conversation: upstream } = await client.getConversation({ id: event.conversationId })
const downstreamConvId = upstream.tags?.['hitl#downstream']

if (downstreamConvId) {
  const { conversation: downstream } = await client.getConversation({ id: downstreamConvId })
  const assignedAtMs = parseInt(downstream.tags?.['hitl:assignedAt'] || '0')

  if (assignedAtMs) {
    const requestTime = new Date(conversation.hitlRequestTimestamp)
    const assignedTime = new Date(assignedAtMs)

    const diffMs = assignedAtMs - Number(conversation.hitlRequestTimestamp)
    const diffMins = Math.floor(diffMs / 60000)
    const diffSecs = Math.floor((diffMs % 60000) / 1000)

    const fmt = (d) =>
      d.toLocaleTimeString('en-US', {
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit',
        hour12: true,
        timeZone: 'America/New_York'
      })

    conversation.hitlTimingDisplay =
      `HITL Request Time: ${fmt(requestTime)}\n` +
      `HITL Assignment Time: ${fmt(assignedTime)}\n` +
      `Wait Time: ${diffMins}m ${diffSecs}s`
  }
}
```

What this code does:

* Fetches the upstream conversation using the current conversation ID.
* Resolves the downstream HITL conversation via the `hitl#downstream` tag (set automatically by Botpress when a handoff is initiated).
* Reads the `hitl:assignedAt` tag from the downstream conversation (timestamp of when an agent accepted and assigned).
* Computes the wait time between the request and assignment.
* Formats and stores the result in `conversation.hitlTimingDisplay`.

Once the code runs, `conversation.hitlTimingDisplay` will contain a message in this format:

```
HITL Request Time: 8:28:07 PM
HITL Assignment Time: 8:28:31 PM
Wait Time: 0m 24s
```

<Note>
  Times are displayed in the America/New\_York timezone. Update the `timeZone` value in the `fmt` function if your team operates in a different timezone.
</Note>

## 4. Use the data

The `conversation.hitlTimingDisplay` variable is available for the rest of your Workflow. You can:

* **Display it in chat**: Add a [Text](/docs/studio/concepts/cards/send-messages#text) Card and reference `{{conversation.hitlTimingDisplay}}` to send the summary to the conversation (useful for testing and QA).
* **Log it to a Botpress Table**: Use an [Update Table Row](/docs/studio/concepts/cards/tables#update-record) or [Insert Table Row](/docs/studio/concepts/cards/tables#insert-record) Card to persist the data for reporting.
* **Send it to an external system**: Use an [Execute Code](/docs/studio/concepts/cards/execute-code) Card with an `axios` or `fetch` call to forward the values to your analytics platform, CRM, or data warehouse.

<Check>
  You can now measure Time to First Agent Response for HITL conversations and use the result in your bot Workflows, tables, or external systems.
</Check>


# HubSpot
Source: https://botpress.com/docs/integrations/integration-guides/hubspot

Add a bot to HubSpot using the official integration.

<OpenInHub />

The official HubSpot integration allows your bot to interact with your HubSpot account.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [HubSpot account](https://hubspot.com)
</Info>

1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
2. Search for the **HubSpot** integration, then select **Install Integration**.
3. In the **Configuration** menu, select **Authorize HubSpot**.
4. Follow the instructions to connect Botpress to your HubSpot account.

<Check>
  Your HubSpot integration is ready—you can use the integration's [Cards](/docs/studio/concepts/cards/introduction) and [Triggers](/docs/studio/concepts/triggers) to interact with your HubSpot account.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Contact

### Create Deal

### Create Lead

### Create Ticket

### Delete Contact

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Deal

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Delete Lead

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Get Company

### Get Contact

### Get Deal

### Get File URL

### Get Lead

### Get Owner

### List Contact Properties

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### List Contacts

### Search Company

### Search Contact

### Search Deal

### Search Lead

### Update Company

### Update Contact

### Update Deal

### Update Lead

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Company Created

### Company Deleted

### Contact Created

### Contact Deleted

### Ticket Created

### Ticket Deleted


# Hunter
Source: https://botpress.com/docs/integrations/integration-guides/hunter

Add a bot to Hunter using the official integration.

<OpenInHub />

The official Hunter integration allows your bot to interact with your Hunter leads.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Hunter account](https://hunter.io/users/sign_up)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Hunter** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API key**. Leave it empty for now—you'll come back to it after getting your Hunter API key.
  </Step>

  <Step title="Get your Hunter API key">
    Next, get your Canny API key:

    1. [Log in to your Hunter dashboard](https://hunter.io/users/sign_in).
    2. From the left sidebar, go to **API**.
    3. Copy your API key.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your Hunter API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Hunter integration is ready. You can use the integration's [Cards](#cards) to interact with your Hunter leads.
</Check>

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Lead

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="lead" type="object">
      <Expandable>
        <ResponseField name="first_name" type="string | null" />

        <ResponseField name="last_name" type="string | null" />

        <ResponseField name="position" type="string | null" />

        <ResponseField name="company" type="string | null" />

        <ResponseField name="company_industry" type="string | null" />

        <ResponseField name="company_size" type="string | null" />

        <ResponseField name="confidence_score" type="number | null" />

        <ResponseField name="website" type="string | null" />

        <ResponseField name="country_code" type="string | null" />

        <ResponseField name="source" type="string | null" />

        <ResponseField name="linkedin_url" type="string | null" />

        <ResponseField name="phone_number" type="string | null" />

        <ResponseField name="twitter" type="string | null" />

        <ResponseField name="sync_status" type="string | null" />

        <ResponseField name="notes" type="string | null" />

        <ResponseField name="sending_status" type="string | null" />

        <ResponseField name="last_activity_at" type="string | null" />

        <ResponseField name="last_contacted_at" type="string | null" />

        <ResponseField name="verification" type="object">
          <Expandable>
            <ResponseField name="date" type="string | null" />

            <ResponseField name="status" type="string | null" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Create or update Lead

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="lead" type="object">
      <Expandable>
        <ResponseField name="first_name" type="string | null" />

        <ResponseField name="last_name" type="string | null" />

        <ResponseField name="position" type="string | null" />

        <ResponseField name="company" type="string | null" />

        <ResponseField name="company_industry" type="string | null" />

        <ResponseField name="company_size" type="string | null" />

        <ResponseField name="confidence_score" type="number | null" />

        <ResponseField name="website" type="string | null" />

        <ResponseField name="country_code" type="string | null" />

        <ResponseField name="source" type="string | null" />

        <ResponseField name="linkedin_url" type="string | null" />

        <ResponseField name="phone_number" type="string | null" />

        <ResponseField name="twitter" type="string | null" />

        <ResponseField name="sync_status" type="string | null" />

        <ResponseField name="notes" type="string | null" />

        <ResponseField name="sending_status" type="string | null" />

        <ResponseField name="last_activity_at" type="string | null" />

        <ResponseField name="last_contacted_at" type="string | null" />

        <ResponseField name="verification" type="object">
          <Expandable>
            <ResponseField name="date" type="string | null" />

            <ResponseField name="status" type="string | null" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Delete Lead

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Get Leads

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="search" type="object">
      <Expandable>
        <ResponseField name="sync_status" type="enum<string>">
          Available options: `pending`, `error`, `success`
        </ResponseField>

        <ResponseField name="last_activity_at" type="enum<string>">
          Available options: `*`, `~`
        </ResponseField>

        <ResponseField name="last_contacted_at" type="enum<string>">
          Available options: `*`, `~`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="leads" type="array">
      <Expandable title="array item properties">
        <ResponseField name="first_name" type="string | null" />

        <ResponseField name="last_name" type="string | null" />

        <ResponseField name="position" type="string | null" />

        <ResponseField name="company" type="string | null" />

        <ResponseField name="company_industry" type="string | null" />

        <ResponseField name="company_size" type="string | null" />

        <ResponseField name="confidence_score" type="number | null" />

        <ResponseField name="website" type="string | null" />

        <ResponseField name="country_code" type="string | null" />

        <ResponseField name="source" type="string | null" />

        <ResponseField name="linkedin_url" type="string | null" />

        <ResponseField name="phone_number" type="string | null" />

        <ResponseField name="twitter" type="string | null" />

        <ResponseField name="sync_status" type="string | null" />

        <ResponseField name="notes" type="string | null" />

        <ResponseField name="sending_status" type="string | null" />

        <ResponseField name="last_activity_at" type="string | null" />

        <ResponseField name="last_contacted_at" type="string | null" />

        <ResponseField name="verification" type="object">
          <Expandable>
            <ResponseField name="date" type="string | null" />

            <ResponseField name="status" type="string | null" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Retrieve Lead

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="lead" type="object">
      <Expandable>
        <ResponseField name="first_name" type="string | null" />

        <ResponseField name="last_name" type="string | null" />

        <ResponseField name="position" type="string | null" />

        <ResponseField name="company" type="string | null" />

        <ResponseField name="company_industry" type="string | null" />

        <ResponseField name="company_size" type="string | null" />

        <ResponseField name="confidence_score" type="number | null" />

        <ResponseField name="website" type="string | null" />

        <ResponseField name="country_code" type="string | null" />

        <ResponseField name="source" type="string | null" />

        <ResponseField name="linkedin_url" type="string | null" />

        <ResponseField name="phone_number" type="string | null" />

        <ResponseField name="twitter" type="string | null" />

        <ResponseField name="sync_status" type="string | null" />

        <ResponseField name="notes" type="string | null" />

        <ResponseField name="sending_status" type="string | null" />

        <ResponseField name="last_activity_at" type="string | null" />

        <ResponseField name="last_contacted_at" type="string | null" />

        <ResponseField name="verification" type="object">
          <Expandable>
            <ResponseField name="date" type="string | null" />

            <ResponseField name="status" type="string | null" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Update Lead

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>


# Improvement
Source: https://botpress.com/docs/integrations/integration-guides/improvement



The official Improvement integration lets you provide feedback on your bot's responses in the [emulator](/docs/studio/concepts/emulator). Your bot can then use that feedback when generating future responses.

## Setup

The Improvement integration comes pre-installed on every bot. If you need to install it manually:

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
</Info>

<Steps>
  <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
  <Step>Search for the **Improvement** integration, then select **Install Integration**.</Step>
  <Step>In the **Configuration** menu, select **Save Configuration**.</Step>
</Steps>

## Suggesting improvements

You can suggest improvements when chatting with your bot in the emulator:

<Steps>
  <Step>
    Select <Icon icon="pencil" /> **Improve Response** on any message:

    <Frame>
      <img alt="Improve response" />

      <img alt="Improve response" />
    </Frame>
  </Step>

  <Step>
    Enter your feedback and select <Icon icon="refresh-ccw" /> **Re-generate**., This will show you a preview of an updated response based on your feedback:

    <Frame>
      <img alt="Feedback" />

      <img alt="Feedback" />
    </Frame>

    The **Code** section shows you exactly how your bot's execution will be different after the feedback is applied.
  </Step>

  <Step>
    If you're happy with the updated response, select <Icon icon="save" /> **Save as learning**.
  </Step>
</Steps>

## Managing feedback

Any time you save feedback, it gets added to the **Feedback** [Table](/docs/studio/concepts/tables) as a row:

<Frame>
  <img alt="Feedback" />

  <img alt="Feedback" />
</Frame>

Your bot reads directly from this table when applying your feedback. This means you can modify the table's rows and columns to modify how feedback is applied.

You can also delete a specific piece of feedback by deleting its associated table row.


# Instagram
Source: https://botpress.com/docs/integrations/integration-guides/instagram

Add your bot to Instagram using the official integration.

<OpenInHub />

The official Instagram integration allows your users to chat with your bot by messaging an Instagram account.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [professional Instagram account](https://help.instagram.com/138925576505882?helpref=faq_content). If you have a personal Instagram account, the setup wizard will ask you to switch to a professional account.
    </Info>

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Instagram** integration, then select **Install Integration**.
    3. In the **Configuration** menu, select **Authorize Instagram**.
    4. Follow the instructions to connect Botpress to your Instagram account.
  </Tab>

  <Tab title="Manual configuration">
    You can also manually configure the Instagram integration with your own Meta app.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Meta developer app](https://developers.facebook.com/apps/creation/). Check out the [Meta developer documentation](https://developers.facebook.com/docs/instagram-platform) to learn more about the setup process.
      * A [professional Instagram account](https://help.instagram.com/138925576505882?helpref=faq_content). If you have a personal Instagram account, the setup wizard will ask you to switch to a professional account.
    </Info>

    <Steps>
      <Step title="Install the integration">
        First, install the integration to your bot:

        1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
        2. Search for the **Instagram** integration, then select **Install Integration**.
        3. In the **Configuration** menu, open the drop-down menu and select **Manual Configuration**.
        4. Copy the webhook URL—it should begin with `webhook.botpress.cloud`.
      </Step>

      <Step title="Add the Instagram API">
        To configure your integration, you need to access the Instagram API:

        1. Login to your [Meta developer account](https://developers.facebook.com/apps/).
        2. Select the app you want to use with the integration.
        3. From the left navigation bar, select **Add Product**.
        4. Under the **Instagram** section, select **Set up**.
      </Step>

      <Step title="Configure Instagram Tester role">
        Next, add an Instagram Tester role to your Meta App:

        1. From the left navigation bar, select **App roles**, then **Roles**.
        2. Select **Add People**, then **Instagram Tester**.
        3. Enter your Instagram username, then select **Add**.
        4. Login to your Instagram account, then open the [Apps and websites](https://www.instagram.com/accounts/manage_access/) settings.
        5. Open the **Tester Invites** tab, then select **Accept**.
      </Step>

      <Step title="Configure the integration">
        To configure the integration, you need to create a webhook endpoint for the WhatsApp integration. To do this, fill in the integration’s configuration fields:

        <AccordionGroup>
          <Accordion title="Client Secret">
            1. From your Meta app's left sidebar, expand **Instagram** and select **API setup with Instagram login**.

            <Warning>
              Make sure you're in **API setup with Instagram login** and not **API setup with Facebook login**.
            </Warning>

            2. Copy the code under **Instagram app secret**.
            3. Go back to the integration's configuration menu in Botpress.
            4. Paste the code into the **Client Secret** field.
          </Accordion>

          <Accordion title="Verify Token">
            Used by Meta to verify that you’re the real owner of the provided webhook. Can be any alphanumeric string.
          </Accordion>

          <Accordion title="Access Token">
            1. From your Meta app's left sidebar, expand **Instagram** and select **API setup with Instagram login**.

            <Warning>
              Make sure you're in **API setup with Instagram login** and not **API setup with Facebook login**.
            </Warning>

            2. Expand **Generate access tokens**, then **Generate token**.
            3. Select **Allow**, then copy the access token.
            4. Go back to the integration's configuration menu in Botpress.
            5. Paste the access token into the **Access token** field.
          </Accordion>

          <Accordion title="Instagram Account ID">
            1. From your Meta app's left sidebar, expand **Instagram** and select **API setup with Instagram login**.

            <Warning>
              Make sure you're in **API setup with Instagram login** and not **API setup with Facebook login**.
            </Warning>

            2. Expand **Generate access tokens**. Then, copy the number under your Instagram account handle.
            3. Go back to the integration's configuration menu in Botpress.
            4. Paste the number into the **Instagram Account ID** field.
          </Accordion>
        </AccordionGroup>

        When you’ve filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
      </Step>

      <Step title="Set up the Instagram API">
        Now, you can set up the Instagram API and add the webhook to your Meta app:

        1. Go back to your Meta developer dashboard, then select **Instagram** from the left navigation bar.
        2. Select **API setup with Instagram login**.
        3. Under **Configure webhooks**, paste your Botpress webhook URL into the **Callback URL** field.
        4. In the **Verify token** field, enter the same token you created in the [previous step](integrations/integration-guides/instagram#verify-token).
        5. Select **Verify and save**.

        <Note>
          If you receive an error message after selecting **Verify and save**, make sure you saved your integration's configuration properly in the previous step.
        </Note>

        6. Now,  select the required subscriptions for your webhook. Select **Add Subscriptions**, then select:
           * `messages`
           * `messaging_postbacks`
           * `instagram_manage_messages` (if your app has been [reviewed by Meta](#submit-your-app-for-meta-review)
        7. Select **Save**.
      </Step>
    </Steps>

    <Check>
      You’ve manually configured your Instagram integration!
    </Check>

    ### Submit your app for Meta review

    After setup is complete, you can submit your app for [review by Meta](/docs/integrations/integration-guides/instagram#submit-your-app-for-meta-review), the parent company of WhatsApp. This verification confirms the identity and eligibility of your business to use Meta’s platforms.

    While the review is pending, your bot will work for admins, developers, and testers of the app only. After your app is approved and made public, it will work for the general public as well.
  </Tab>

  <Tab title="Playground">
    If you want to test your bot’s behaviour in Instagram before going through the actual setup process, you can use the Instagram integration playground.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [professional Instagram account](https://help.instagram.com/138925576505882?helpref=faq_content). If you have a personal Instagram account, the setup wizard will ask you to switch to a professional account.
    </Info>

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the Instagram integration, then select **Install Integration**.
    3. Select **Test your agent on Instagram**.
    4. Follow the instructions to set up the playground.
  </Tab>
</Tabs>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get or Create a Conversation

### Get or Create a User


# Intercom
Source: https://botpress.com/docs/integrations/integration-guides/intercom



<OpenInHub />

<img />

## Introduction

Intercom is a Conversational Relationship Platform (CRP) that helps businesses build better customer relationships through personalized, messenger-based experiences across the customer journey. By integrating it with Botpress you can leverage AI to automate your customer support and sales processes.

## Prerequisites

* An [Intercom account](https://www.intercom.com/)
* Administrator or Developer access to a Intercom workspace

## Setting up the Intercom integration in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Intercom integration then click on the "Install to Bot" button, now go back to your bot settings.

The Intercom integration has the following settings:

* **Enabled**: Whether Botpress will communicate with Intercom
* **Webhook URL**: The URL for receiving data in Botpress
* **Access Token**: The access token for the Intercom app
* **Admin ID**: The admin id for the Intercom app

## Setting up Intercom

<Info>
  Info

  In this tutorial we're going to be using a standard production workspace, but you can also create a [Test workspace](https://www.intercom.com/help/en/articles/188-create-a-test-workspace-in-intercom) to test the integration before deploying it to production.

  To do that, open the Settings of a production workspace, go to the General settings tab, look for "Enable a test workspace" and click "Save". Now, you just need to use this workspace in the steps below.

  After verifying that the integration works, you will need to repeat the steps below using the production workspace! Don't create the app again, just go to the app settings (Test and publish > Your workspaces) and install it to the production workspace.
</Info>

### Creating an App

In order to communicate with Botpress, you need to create a developer app in Intercom.

1. Go to the [Developer Hub](https://developers.intercom.com/) in Intercom then click "Your Apps"
2. Click "New App", give it a name like `Botpress connector`, then select the desired workspace and click "Create App"
3. You will be redirected to the app's Authentication settings page. Copy the Access Token and paste it in the Botpress integration settings.

### Getting the Admin ID

1. Open Intercom and hover over your avatar in the bottom left corner, then click your avatar again to see your profile
2. Copy the last number in the URL (as shown below); this is your Admin ID. Paste it in the Botpress integration settings

<img />

### Setting up the Webhook

1. Copy the Webhook URL provided in the Botpress integration settings
2. Go back to the Intercom app settings and open the "Webhooks" tab
3. Paste the URL in the "Endpoint URL" section
4. Click the "Select a topic" dropdown under the "Topics" section, a list is going to show up
5. Search for `user` and click the options `conversation.user.created` and `conversation.user.replied`. Now, exit the list. A "Topic" section should appear with the selected topics. Click "Save" to finalize the webhook configuration.

### Adding a Default conversation Assignee

1. Go back to the Intercom app settings and open the "Inbox" tab
2. Click "Inbox settings" then "Workload management"
3. In the "Default assignee" section select yourself or another user to receive the conversations from the bot (it needs to be the same user as the Admin ID)

[For more information](https://www.intercom.com/help/en/articles/6561699-assign-conversations-to-teammates-and-teams)

### Finalizing the configuration

Now you just need to **Enable** the integration in the Botpress settings and click "Save configuration".

That's it, you may now start chatting with your bot on Intercom!

## Additional options

### Get User Email

1. Access the user’s email from the event object:

`event.tags.user['intercom:email']`

2. Using the user email, you can retrieve detailed profile information from Intercom:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const email = event.tags.user['intercom:email'];
await axios.post('https://api.intercom.io/contacts/search', {
    query: {
      field: 'email',
      operator: '=',
      value: email
    }
  }, {
    headers: {
      Authorization: `Bearer $\{intercomToken}`
    }
  })
  .then((response) => {
    response.data.data.forEach((key) => {
      //Contact details
    });
  });
```

##### Unassign a Conversation:

To unassign a conversation in Intercom (make it "unassigned"):

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const intercomApiUrl = `https://api.intercom.io/conversations/${intercomConvoId}/parts`;

const headers = {
  Authorization: `Bearer ${intercomApiToken}`,
  'Content-Type': 'application/json'
};

await axios.post(
  intercomApiUrl,   {
    admin_id: adminId,
    type: 'admin',
    assignee_id: '0',
    message_type: 'assignment'
  },
  { headers }
);
```


# Klaviyo
Source: https://botpress.com/docs/integrations/integration-guides/klaviyo

Add a bot to Klaviyo using the official integration.

<OpenInHub />

The official Klaviyo integration allows your bot to interact with your Klaviyo account. You can use it to:

* Create or update user profiles
* Retrieve individual or bulk user profile data
* Subscribe users to SMS/email marketing

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Klaviyo account](https://www.klaviyo.com/sign-up)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Klaviyo** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API Key**. Leave it empty for now—you'll come back to it after creating your Klaviyo API key.
  </Step>

  <Step title="Create a Klaviyo private API key">
    Next, create a private Klaviyo API key:

    1. [Log in to your Klaviyo account](https://www.klaviyo.com/login).
    2. Select your organization's name in the bottom-left corner.
    3. Select **Settings**. Then, navigate to **API keys**.
    4. Under **Private API Keys**, select **Create Private API Key**.
    5. Enter a name for the API key.
    6. Check **Full Access** for the following API scopes:
       * **Profiles**
       * **Subscriptions**
    7. Select **Create** in the upper-right corner.
    8. Copy the API key—it should start with `pk`.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your Klaviyo API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Klaviyo integration is ready. You can use the integration's [Cards](#cards) to interact with your Klaviyo account.
</Check>

***

## Cards

<Warning>
  If you use any of the following Cards in an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node), keep in mind that your bot will fill in the Card's fields based on the user's responses. This can lead to unexpected behaviour for fields that have strict conventions.

  For example, the [Update Profile](#update-profile) Card lets you update [custom properties](#param-custom-properties-2) associated with a profile. If the user isn't specific about that property's exact name, the bot may accidentally create a new property instead of updating an existing one.
</Warning>

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Profile

### Get Profile

### Get Profiles

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="filterField" type="enum<string>">
      Available options: `id`, `email`, `phone_number`, `external_id`, `created`, `updated`
    </ResponseField>

    <ResponseField name="filterOperator" type="enum<string>">
      Available options: `equals`, `greater-than`, `less-than`, `greater-or-equal`, `less-or-equal`, `contains`, `starts-with`, `ends-with`
    </ResponseField>

    <ResponseField name="sort" type="enum<string>">
      Available options: `created`, `-created`, `email`, `-email`, `id`, `-id`, `subscriptions.email.marketing.list_suppressions.timestamp`, `-subscriptions.email.marketing.list_suppressions.timestamp`, `subscriptions.email.marketing.suppression.timestamp`, `-subscriptions.email.marketing.suppression.timestamp`, `updated`, `-updated`
    </ResponseField>
  </Expandable>
</ResponseField>

### Subscribe Profiles

### Update Profile


# Knowledge Base Optimizer
Source: https://botpress.com/docs/integrations/integration-guides/knowledge-base-optimization



The official Knowledge Base Optimizer integration improves your bot's ability to respond to questions using information contained in your Knowledge Base.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
</Info>

<Steps>
  <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
  <Step>Search for the **Knowledge Base Optimizer** integration, then select **Install Integration**.</Step>
  <Step>In the **Configuration** menu, select **Save Configuration**.</Step>
</Steps>

## Optimize

Now you can select <Icon icon="wand-sparkles" /> **Auto-optimize** on any of your Knowledge Bases:

<Frame>
  <img alt="Auto-optimize" />

  <img alt="Auto-optimize" />
</Frame>

This improves your bot's ability to respond to queries with the information contained in your Knowledge Bases.

## How it works

The Knowledge Base Optimizer analyzes each document in your Knowledge Base with AI. It then automatically generates smart summaries for every file and creates an overall summary for the entire Knowledge Base.

When your bot gets a question, it uses these summaries—along with the full content—to quickly find and deliver more relevant, accurate answers from your Knowledge Base.


# Kommo
Source: https://botpress.com/docs/integrations/integration-guides/kommo

Connect your bot to Kommo CRM using the official integration.

<OpenInHub />

The official Kommo integration allows your bot to create and update leads, manage contacts, and search your CRM data.

## Setup

<Info>
  Before you begin, you need:

  * A [published bot](/docs/get-started/quick-start)
  * A Kommo account with **administrator** access
  * A **private integration** in your Kommo account
  * A **long-lived access token** from that private integration
</Info>

<Steps>
  <Step title="Install the Kommo integration in Botpress">
    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Kommo** integration, then select **Install Integration**.

    Leave the configuration fields empty for now, you will fill them in after you create the private integration and token in Kommo.
  </Step>

  <Step title="Create a private integration in Kommo">
    1. Log in to your Kommo account.
    2. Go to **Settings** → **Integrations marketplace**.
    3. Select **Create Integration** in the upper-right corner.
    4. Enter a name for your integration.
    5. Select **all** scopes.
    6. Save the integration.
  </Step>

  <Step title="Generate a long-lived access token">
    1. Open your integration’s settings in Kommo.
    2. Select **Generate long-lived token**.
    3. Choose an expiration date.
    4. Copy the long-lived token and store it securely.

    <Note>
      Treat the token like a password. If it is exposed, revoke it in Kommo and generate a new one.
    </Note>
  </Step>

  <Step title="Configure the integration in Botpress">
    In the Kommo integration **Configuration** page in Botpress, enter:

    * **Base Domain**: Your Kommo subdomain only (for example `mycompany.kommo.com`)

      Do not include `https://` or trailing slashes.

    * **Access Token**: The long-lived token from the previous step.

    Select **Save Configuration** and enable the integration.
  </Step>
</Steps>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Contact

### Create Lead

### Search Contacts

### Search Leads

### Update Lead


# Line
Source: https://botpress.com/docs/integrations/integration-guides/line



<OpenInHub />

<img />

## Prerequisites

* A channel created on the [LINE Developers Console](https://developers.line.biz/).
* The same channel added to your LINE official account

## Setting up the LINE integration in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the LINE integration then click on the "Install to Bot" button, now go back to your bot settings.

The LINE integration has the following settings:

* **Enabled**: Whether Botpress will communicate with LINE
* **Webhook URL**: The URL for receiving data in Botpress
* **Channel Access Token**: The token used to authenticate the channel
* **Channel Secret**: The secret used to verify the signature between LINE and Botpress

## Setting up Line

### Channel Access Token

To get this token, open the **Messaging API** tab in your channel settings in LINE, scroll to the bottom to the **Channel Access Token** section, and then generate a new one or copy it if the Channel access token was already issued, then paste it in Botpress.

For Long-Lived Channel Access Token: read this [LINE documentation](https://developers.line.biz/en/docs/messaging-api/channel-access-tokens/#long-lived-channel-access-tokens).

### Channel Secret

The **Channel Secret** is used to [verify the signature](https://developers.line.biz/en/docs/messaging-api/receiving-messages/#verifying-signatures) between LINE and Botpress.

To get the secret, open the **Basic settings** tab in your channel configuration in LINE, scroll to the bottom to the **Channel Secret** section, and then copy the secret.

## Finalizing Channel Configuration

The next step is to **Enable** the channel from the top of the screen and copy the webhook URL from the button below the webhook URL. Then click **Save**.

Now, we proceed to the last step by [setting your webhook URL](https://developers.line.biz/en/docs/messaging-api/building-bot/#setting-webhook-url) in LINE.

That's it, you may now start chatting with your bot on LINE!

## Content Types Mapping

### From Botpress to LINE

* **Text** is mapped to [Text Object](https://developers.line.biz/en/docs/messaging-api/message-types/#text-messages)

* Text with **Markdown** is mapped to [Text Object](https://developers.line.biz/en/docs/messaging-api/message-types/#text-messages)

* **Image** is mapped to [Image Object](https://developers.line.biz/en/docs/messaging-api/message-types/#image-messages)

* **Audio** is mapped to [Audio Object](https://developers.line.biz/en/docs/messaging-api/message-types/#audio-messages)

* **Video** is mapped to [Video Object](https://developers.line.biz/en/docs/messaging-api/message-types/#video-messages)

* **File** isn't supported in LINE [Message Types](https://developers.line.biz/en/docs/messaging-api/message-types/)

* **Location** is mapped to [Location Object](https://developers.line.biz/en/docs/messaging-api/message-types/#location-messages)

* **Carousel** is mapped to [Flex Object](https://developers.line.biz/en/docs/messaging-api/message-types/#flex-messages)

* **Card** is mapped to [Flex Object](https://developers.line.biz/en/docs/messaging-api/message-types/#flex-messages)

* **Dropdown** is mapped to [Flex Object](https://developers.line.biz/en/docs/messaging-api/message-types/#flex-messages)

* **Choice** is mapped to [Flex Object](https://developers.line.biz/en/docs/messaging-api/message-types/#flex-messages)

### From LINE to Botpress

* **Text** is mapped to **Text Object**
* The rest of the types aren't currently processed by Botpress

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get or Create a Conversation

### Get or Create a User


# Linear
Source: https://botpress.com/docs/integrations/integration-guides/linear

Connect your bot to Linear using the official integration.

<OpenInHub />

The official Linear integration lets your bot automate issue workflows and react to repository file events.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Linear](https://linear.app) account with access to the workspace you want to connect
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Linear** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize Linear**.
      </Step>

      <Step>
        Follow the on-screen instructions to connect Botpress to your Linear workspace.
      </Step>
    </Steps>

    <Note>
      When using this configuration mode, Botpress connects to Linear using OAuth. Actions taken by the bot use the Linear account that completed authorization.

      If you need an API key, webhook signing secret, or more control over how Linear sends events to Botpress, use [Manual configuration](#manual-configuration) instead.
    </Note>
  </Tab>

  <Tab title="Manual configuration">
    For advanced use cases, you can configure the integration with a Linear **API key** and **Webhook Signing Secret** instead of OAuth.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Linear](https://linear.app) account with access to the workspace you want to connect
    </Info>

    ### Creating a Linear API key

    <Steps>
      <Step>
        On Linear, navigate to your account settings and select the **API** tab in the navigation sidebar.
      </Step>

      <Step>
        Under **Personal API keys**, enter a name for your API key and select **Create new API key**.
      </Step>

      <Step>
        Save this API key in a secure location. You will need it to configure the Linear integration in Botpress.

        <Note>
          Treat API keys like passwords. Store them securely and rotate them if they’re exposed.
        </Note>
      </Step>
    </Steps>

    ### Subscribing to Linear webhook events

    <Steps>
      <Step>
        In Botpress, open the **Configuration** page for the Linear integration.
      </Step>

      <Step>
        Copy the **Webhook URL** generated by Botpress.
      </Step>

      <Step>
        On Linear, go to your account settings and select the **API** tab in the navigation sidebar.
      </Step>

      <Step>
        Under **Webhooks**, select **Create new webhook**.
      </Step>

      <Step>
        Enter a name for the webhook and paste the webhook URL from Botpress into the **URL** field.
      </Step>

      <Step>
        Copy the **webhook signing secret** and store it in a secure location. You will need it to configure the Linear integration in Botpress.
      </Step>

      <Step>
        Under **Data change events**, choose the events to subscribe to:

        * **Issues**: Receive notifications when issues are created, updated, or deleted.
        * **Comments**: Receive notifications when comments are added to issues.
      </Step>

      <Step>
        Under **Teams**, select the teams you want to receive notifications for.
      </Step>

      <Step>
        Select **Create webhook** to save your changes.
      </Step>
    </Steps>

    ### Configuring the Linear integration in Botpress

    <Steps>
      <Step>
        In Botpress, open the **Configuration** page for the Linear integration.
      </Step>

      <Step>
        Select **Configure Linear with an API Key**.
      </Step>

      <Step>
        Enter the API key from Linear in the **API Key** field.
      </Step>

      <Step>
        Enter the webhook signing secret from Linear in the **Webhook Signing Secret** field.
      </Step>

      <Step>
        Save the configuration and enable the integration.
      </Step>
    </Steps>

    <Check>
      Your Linear integration is ready. Use the **Cards** and **Triggers** sections below to build your workflows.
    </Check>
  </Tab>
</Tabs>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Issue

### Delete Issue

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Find Target

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="channel" type="enum<string>">
      Available options: `issue`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="targets" type="array">
      <Expandable title="array item properties">
        <ResponseField name="channel" type="enum<string>">
          Available options: `issue`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Issue

### Get or Create a Conversation

### Get User Profile

### Issue Delete

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Issue List

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="items" type="array" />
  </Expandable>
</ResponseField>

### List Issues

### List States

### List Teams

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### List Users

### Mark Issue as Duplicate

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Resolve Comment

### Send Raw GraphQL Query

### Update Issue

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Aggregate File Changes

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="modifiedItems" type="object">
      <Expandable>
        <ResponseField name="created" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="updated" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="deleted" type="array">
          <Tabs>
            <Tab title="file">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>

            <Tab title="folder">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>
          </Tabs>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Created

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Deleted

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Folder Deleted Recursive

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="folder" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Issue Created

### Issue Deleted

### Issue Updated


# LinkedIn
Source: https://botpress.com/docs/integrations/integration-guides/linkedin

Add a bot to LinkedIn using the official integration.

<OpenInHub />

The official LinkedIn integration allows your bot to create and delete posts from your LinkedIn account.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [LinkedIn account](https://www.linkedin.com/signup)
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **LinkedIn** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize LinkedIn**.
      </Step>

      <Step>
        Follow the on-screen instructions to connect Botpress to your LinkedIn account.
      </Step>
    </Steps>

    <Note>
      When using this configuration mode, a Botpress-managed LinkedIn application connects to your LinkedIn account. Actions taken by the bot will be attributed to the LinkedIn account that authorized the connection.
    </Note>
  </Tab>

  <Tab title="Manual configuration">
    For advanced use cases, you can manually configure the integration using your own LinkedIn application and OAuth credentials.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [LinkedIn account](https://www.linkedin.com/signup)
      * A [LinkedIn Page](https://www.linkedin.com/help/linkedin/answer/a543852) associated with your app
    </Info>

    ### Step 1: Create a LinkedIn application

    <Steps>
      <Step>
        Go to the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps) and select **Create app**.
      </Step>

      <Step>
        Fill in the required fields:

        * **App name**
        * **LinkedIn Page**
        * **App logo**
      </Step>

      <Step>
        Select **Create app**.
      </Step>
    </Steps>

    ### Step 2: Configure OAuth settings

    <Steps>
      <Step>
        In your LinkedIn application settings, navigate to the **Products** tab.
      </Step>

      <Step>
        Request access to the following products:

        * **Share on LinkedIn** — required for posting content
        * **Sign In with LinkedIn using OpenID Connect** — required for authentication

        <Note>
          Approval may require review by LinkedIn.
        </Note>
      </Step>

      <Step>
        Navigate to the **Auth** tab.
      </Step>

      <Step>
        Under **OAuth 2.0 settings**, add the following redirect URL:

        ```
        https://webhook.botpress.cloud/oauth
        ```
      </Step>

      <Step>
        Copy your **Client ID** and **Client Secret** — you'll need them to configure the integration in Botpress.
      </Step>
    </Steps>

    ### Step 3: Obtain an authorization code

    <Steps>
      <Step>
        Construct the authorization URL by replacing `YOUR_CLIENT_ID` in the following URL with your actual Client ID:

        ```
        https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://webhook.botpress.cloud/oauth&scope=openid%20profile%20email%20w_member_social&state=manual
        ```
      </Step>

      <Step>
        Visit this URL in your browser while logged into the LinkedIn account you want to use with the integration.
      </Step>

      <Step>
        Follow the on-screen instructions to authorize the application.
      </Step>

      <Step>
        You will be redirected to `webhook.botpress.cloud`. Do not close this page.
      </Step>

      <Step>
        Copy the **authorization code** from the URL in your browser's address bar.

        <Note>
          The authorization code is the string that appears after `code=` in the URL.
        </Note>
      </Step>
    </Steps>

    ### Step 4: Configure the integration in Botpress

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **LinkedIn** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select the drop-down and choose **Manual**.
      </Step>
    </Steps>

    Fill in the integration's configuration fields:

    <AccordionGroup>
      <Accordion title="Client ID">
        Paste the Client ID you copied from the **Auth** tab in the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps).
      </Accordion>

      <Accordion title="Client Secret">
        Paste the Client Secret you copied from the **Auth** tab in the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps).
      </Accordion>

      <Accordion title="Authorization Code">
        Paste the authorization code you obtained in [Step 3](#step-3-obtain-an-authorization-code).

        <Warning>
          The authorization code is only valid for a short period of time. If the code has expired, repeat [Step 3](#step-3-obtain-an-authorization-code) to obtain a new one.
        </Warning>
      </Accordion>
    </AccordionGroup>

    When you've filled in all the fields, select **Save Configuration**.

    <Check>
      Your LinkedIn integration has been manually configured and is ready to use.
    </Check>
  </Tab>
</Tabs>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Post

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="visibility" type="enum<string>">
      Available options: `PUBLIC`, `CONNECTIONS`
    </ResponseField>
  </Expandable>
</ResponseField>

### Delete Post


# Loops
Source: https://botpress.com/docs/integrations/integration-guides/loops

Add a bot to Loops using the official integration.

<OpenInHub />

The official Loops integration allows your bot to send emails to your customers via Loops.

## Setup

<Info>
  You will need:

  * A [published bot](https://botpress.com/docs/get-started/quickstart)
  * A [Loops account](https://app.loops.so/)
</Info>

### Step 1: Install the integration in Botpress

First, install the integration in Botpress:

<Steps>
  <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
  <Step>Search for the **Loops** integration, then select **Install Integration**.</Step>
  <Step>In the **Configuration** menu, you should see two fields: **API Key** and **Webhook Signing Secret**. Leave these blank for now—you'll come back to them after configuring the integration in Loops.</Step>
  <Step>Copy the webhook URL.</Step>
</Steps>

### Step 2: Configure the webhook in Loops

Next, configure your Botpress webhook in Loops:

<Steps>
  <Step>
    Log in to your Loops account.
  </Step>

  <Step>
    Go to **Settings** > **Webhook**.
  </Step>

  <Step>
    Paste your integration's webhook URL into the **Endpoint URL** field, then select **Update URL**.
  </Step>

  <Step>
    Copy the generated **Signing Secret**.
  </Step>

  <Step>
    Paste it into the integration's **Webhook Signing Secret** field in Botpress.
  </Step>
</Steps>

### Step 3: Create a Loops API key

Then, create your Loops API key:

<Steps>
  <Step>
    In your Loops account, go to **Settings** > **API**.
  </Step>

  <Step>
    Select **Generate key**.
  </Step>

  <Step>
    Copy the generated key, then paste it into the integration's **API Key** field in Botpress.
  </Step>
</Steps>

<Check>
  Your Loops integration is ready. You can use the integration's [Cards](#cards) and [Triggers](#triggers) to interact with your customer emails.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Send Transactional Email

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Email Clicked

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`
    </ResponseField>
  </Expandable>
</ResponseField>

### Email Delivered

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`, `transactional`
    </ResponseField>
  </Expandable>
</ResponseField>

### Email Hard Bounced

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`, `transactional`
    </ResponseField>
  </Expandable>
</ResponseField>

### Email Opened

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`
    </ResponseField>
  </Expandable>
</ResponseField>

### Email Soft Bounced

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`, `transactional`
    </ResponseField>
  </Expandable>
</ResponseField>

### Email Spam Reported

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`, `transactional`
    </ResponseField>
  </Expandable>
</ResponseField>

### Email Unsubscribed

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="sourceType" type="enum<string>">
      Available options: `campaign`, `loop`
    </ResponseField>
  </Expandable>
</ResponseField>


# MailerLite
Source: https://botpress.com/docs/integrations/integration-guides/mailerlite

Add a bot to MailerLite using the official integration.

<OpenInHub />

The official MailerLite integration allows your bot to create, update, fetch, or delete your MailerLite subscribers.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [MailerLite account](https://www.mailerlite.com/signup)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **MailerLite** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API Key**. Leave it empty for now—you'll come back to it after creating your MailerLite API key.
  </Step>

  <Step title="Create a MailerLite developer API key">
    Next, create a MailerLite API key:

    1. [Log in to your MailerLite account](https://accounts.mailerlite.com/?lang=en).
    2. Select **Integrations** from the left navigation bar.
    3. To the right of **API**, select **Use**.
    4. Select **Generate new token**. Enter a name, then select **Create token**.
    5. Copy the API  token.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your MailerLite developer API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your MailerLite integration is ready. You can use the integration's [Cards](#cards) to interact with your MailerLite subscribers.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Delete Subscriber

### Fetch Subscriber

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="subscriber" type="object">
      <Expandable>
        <ResponseField name="fields" type="object">
          <Expandable>
            <ResponseField name="city" type="string | null" />

            <ResponseField name="company" type="string | null" />

            <ResponseField name="country" type="string | null" />

            <ResponseField name="last_name" type="string | null" />

            <ResponseField name="name" type="string | null" />

            <ResponseField name="phone" type="string | null" />

            <ResponseField name="state" type="string | null" />

            <ResponseField name="zip" type="string | null" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Upsert Subscriber

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="fields" type="object">
      <Expandable>
        <ResponseField name="city" type="string | null" />

        <ResponseField name="company" type="string | null" />

        <ResponseField name="country" type="string | null" />

        <ResponseField name="last_name" type="string | null" />

        <ResponseField name="name" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="state" type="string | null" />

        <ResponseField name="zip" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Subscriber Created

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="fields" type="object">
      <Expandable>
        <ResponseField name="city" type="string | null" />

        <ResponseField name="company" type="string | null" />

        <ResponseField name="country" type="string | null" />

        <ResponseField name="last_name" type="string | null" />

        <ResponseField name="name" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="state" type="string | null" />

        <ResponseField name="zip" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Troubleshooting

If you run into errors when using the integration's Cards, check out your bot's [Logs](/docs/studio/concepts/debugger-logs-json#logs) and locate the error message:

<AccordionGroup>
  <Accordion title="An unexpected error occurred">
    Your developer API token may have been revoked. [Create a new one](#setup) and update your bot's configuration.
  </Accordion>

  <Accordion title="Invalid JSON">
    If you're passing data into the [Upsert Subscriber](#upsert-subscriber) Card's [`customFields`](#param-custom-fields) parameter, make sure it's a valid JSON string of key-value pairs..
  </Accordion>
</AccordionGroup>


# Messenger and Facebook
Source: https://botpress.com/docs/integrations/integration-guides/messenger

Add your bot to Messenger and Facebook using the official integration

<OpenInHub />

The official Messenger and Facebook integration allows users to chat with your bot by messaging a Facebook page.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Facebook page](https://www.facebook.com/pages/create/)
    </Info>

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Messenger** integration, then select **Install Integration**.
    3. In the **Configuration** menu, select **Authorize Messenger**.
    4. Follow the instructions to connect Botpress to your Messenger account.
  </Tab>

  <Tab title="Manual configuration">
    For advanced use cases, you can use your own Meta app with our integration.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Facebook page](https://www.facebook.com/pages/create/)
      * A [Meta developer app](https://developers.facebook.com/apps/creation/). Check out the [Meta developer documentation](https://developers.facebook.com/docs/development/create-an-app) to learn more about the setup process.
    </Info>

    ### Get your Meta app ready

    Before setting up the integration in Botpress, you need to get your Meta app ready:

    <Steps>
      <Step title="Add the Messenger API">
        To configure your integration, you need to access the Messenger API:

        1. Log in to your [Meta developer account](https://developers.facebook.com/apps/).
        2. Select the app you want to use with the integration.
        3. Scroll to **Add products to your app**.
        4. Under the **Messenger** section, select **Set up**.
      </Step>

      <Step title="Add your Facebook page">
        To add your Facebook page to the Messenger API configuration:

        1. In your Meta app's left sidebar, go to **Messenger > Messenger API Settings**.
        2. Scroll to **Generate access tokens**, then select **Connect**.
        3. Follow the on-screen instructions to add your Facebook page.
      </Step>

      <Step title="Check your API version">
        Next, check that your API version is 15.0 or higher:

        1. In your Meta app's left sidebar, go to **App settings > Advanced**.
        2. In the **Upgrade API version** section, make sure the version is 15.0 or higher.
        3. If you updated the version, select **Save changes** in the bottom-right corner.
      </Step>
    </Steps>

    ### Set up the integration in Botpress

    [Once your Meta app is ready](#get-your-meta-app-ready), you can set up the integration in Botpress:

    <Steps>
      <Step title="Install the integration">
        1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
        2. Search for the **Messenger and Facebook** integration, then select **Install Integration**.
        3. In the **Configuration** menu, select the drop-down menu, then select **Configure by manually supplying the Meta app details**.
      </Step>

      <Step title="Configure the integration">
        To configure the integration, you need to create a webhook endpoint for the Messenger integration. To do this, fill in the integration's configuration fields using information from your Meta app:

        <AccordionGroup>
          <Accordion title="Client ID">
            To get your Meta app's client ID:

            1. In your Meta app's left sidebar, go to **App settings > Basic**.
            2. Copy the **App ID**, then paste it in the **Client ID** field in Botpress.
          </Accordion>

          <Accordion title="Client Secret (Optional)">
            <Note>
              The client secret is used to check the webhook's signature. You can leave this field empty to disable signature check.
            </Note>

            To get your Meta app's client secret:

            1. In your Meta app's left sidebar, go to **App settings > Basic**.
            2. Copy the **App secret**, then paste it in the **Client Secret** field in Botpress.
          </Accordion>

          <Accordion title="Verify Token">
            Used by Meta to verify that you’re the real owner of the provided webhook. Can be any alphanumeric string.
          </Accordion>

          <Accordion title="Access Token">
            To get your Meta app's access token:

            1. In your Meta app's left sidebar, go to **Messenger > Messenger API Settings**.
            2. Scroll to **Generate access tokens**, then find your Facebook page.
            3. Select **Generate**, then copy the token.
            4. Paste it into the **Access Token** field in Botpress.
          </Accordion>

          <Accordion title="Page ID">
            To get your Meta app's page ID:

            1. In your Meta app's left sidebar, go to **Messenger > Messenger API Settings**.
            2. Scroll to **Generate access tokens**, then find your Facebook page.
            3. Copy the number under your page's name, then paste it into the **Page ID** field in Botpress.
          </Accordion>
        </AccordionGroup>

        When you’ve filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
      </Step>
    </Steps>

    ### Finalize the integration

    Now that your Botpress webhook endpoint is ready, you can add it to your Meta app:

    <Steps>
      <Step title="Get the webhook URL and Verify Token">
        In Botpress, copy:

        * The integration's webhook URL. It should start with `https://webhook.botpress.cloud/`
        * The **Verify Token** you created
      </Step>

      <Step title="Configure the webhook in Meta">
        1. Go back to your Meta app. In the left sidebar, go to **Messenger > Messenger API Settings**.
        2. Scroll to **Configure webhooks**
        3. Paste:
           * Your webhook URL into the **Callback URL** field.
           * Your **Verify Token** into the **Verify token** field.
        4. Select **Verify and save**.

        <Note>
          Make sure you saved your integration's configuration after [configuring it in Botpress](#set-up-the-integration-in-botpress)—otherwise, the webhook validation will fail.
        </Note>
      </Step>

      <Step title="Subscribe to webhook fields">
        Under **Webhook fields**, subscribe to:

        * `messages`
        * `messaging_postbacks`
        * `feed`
      </Step>
    </Steps>

    ### Submit app for review

    The integration is configured, but will only work for admins, developers, and testers. To make it available for public use, make sure you [submit it for review by Meta](https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review/submission-guide).

    <Check>
      You've manually configured your Messenger integration.
    </Check>
  </Tab>

  <Tab title="Playground">
    If you want to test your bot's behaviour in Messenger before going through the actual setup process, you can use the Messenger integration playground.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Facebook account](https://www.facebook.com/r.php?entry_point=login)
    </Info>

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Messenger** integration, then select **Install Integration**.
    3. Select **Test your agent on Messenger**.
    4. Follow the instructions to set up the playground.
  </Tab>
</Tabs>

***

## Options

The Messenger integration's **Configuration** menu offers a few additional options:

### Get user profile

When this option is enabled (default), the integration will update the Botpress user's name and picture URL with data from Messenger.

<Note>
  This option is only available with [manual configuration](#manual-configuration).
</Note>

### Download media

When enabled, this option automatically downloads media files using the [Files API](/docs/api-reference/files-api/getting-started). When disabled, media files are displayed using their Messenger media URL.

### Downloaded media expiry

Expiry time (in hours) for downloaded media files. An expiry time of 0 means the files will never expire. Defaults to 24 hours.

***

## Replying to comments in DM

You can configure your bot to reply to user comments in a direct message (DM).

### Step 1: Check where the conversation started

First, add a router Node that checks whether the conversation originated from a user's comment.

<Steps>
  <Step>
    In Botpress Studio, enter your [Main Workflow](/docs/studio/concepts/workflows#main).
  </Step>

  <Step>
    [Add a new Node](/docs/studio/concepts/nodes/introduction#add-a-node) to the Workflow.
  </Step>

  <Step>
    Rename the Node to `Router`, then move it between the [Start Node](/docs/studio/concepts/nodes/introduction) and any other existing Nodes:

    <Frame>
      <img alt="Reply to comments in DMs 1" />

      <img alt="Reply to comments in DMs 1" />
    </Frame>
  </Step>

  <Step>
    Add two [Expression Cards](/docs/studio/concepts/cards/flow-logic#expression) to the `Router` Node.
  </Step>

  <Step>
    Open the second Expression Card's [inspector](/docs/studio/concepts/cards/introduction#configure-a-card). Next to the **Condition** field, toggle <AiIcon /> to disable generative AI.
  </Step>

  <Step>
    Configure this Card for conversations started normally:

    * In the **Label** field, paste in: `Conversation started`
    * In the **Condition** field, paste in: `{{event.channel == 'channel'}}`
  </Step>

  <Step>
    Open the first Expression Card's [inspector](/docs/studio/concepts/cards/introduction#configure-a-card). Next to the **Condition** field, toggle <AiIcon /> to disable generative AI.
  </Step>

  <Step>
    Configure this Card for conversations started from a comment reply:

    * In the **Label** field, paste in: `Conversation started from comment`
    * In the **Condition** field, paste in: `{{event.channel == 'commentReplies'}}`
  </Step>

  <Step>
    Attach the Start Node to the `Router` Node. Then, attach the `Conversation started` Expression Card to your regular conversation logic:

    <Frame>
      <img alt="Reply to comments in DMs 2" />

      <img alt="Reply to comments in DMs 2" />
    </Frame>
  </Step>
</Steps>

### Step 2: Reply to the user's comment

Next, add logic to reply to the user's comment. This lets them know that the bot will continue the conversation in a DM.

<Steps>
  <Step>
    Add a new Node to your Workflow and rename it to `Reply_to_comment`.
  </Step>

  <Step>
    Add a [Text Card](/docs/studio/concepts/cards/send-messages#text) to the new Node.
  </Step>

  <Step>
    Open the Text Card's inspector.

    In the **Message to send** field, enter the message you want to reply to the user's comment. For example: `Check your DMs!`.
  </Step>

  <Step>
    Attach the `Conversation started from comment` Expression Card to the `Reply_to_comment` Node:

    <Frame>
      <img alt="Reply to comments in DMs 3" />

      <img alt="Reply to comments in DMs 3" />
    </Frame>
  </Step>
</Steps>

### Step 3: Start a DM conversation from the comment

Finally, add logic to start a DM conversation whenever a user leaves a comment.

<Steps>
  <Step>
    Add a new Node to your Workflow and rename it to `DM_reply`.
  </Step>

  <Step>
    Add the [Start DM Conversation from Comment](#start-dm-conversation-from-comment) Card to the new Node.
  </Step>

  <Step>
    Open the Start DM Conversation from Comment Card's inspector.

    * In the **Comment ID** field, paste in: `{{event.payload.commentId}}`
    * In the **Message** field, enter the first message you want to send the user in a DM. For example: `Hey! Received your comment.`

    <Note>
      If you want to send the user's original comment back to them, you can add `{{event.payload.text}}` to the **Message** field.
    </Note>
  </Step>

  <Step>
    Attach the `Reply_to_comment` Node to the `DM_reply` Node. Then, attach the `DM_reply` Node to the [End Node](/docs/studio/concepts/nodes/introduction#end):

    <Frame>
      <img alt="Reply to comments in DMs 4" />

      <img alt="Reply to comments in DMs 4" />
    </Frame>
  </Step>
</Steps>

<Check>
  When a user comments on a post, your bot will now:

  * Reply to their comment, letting them know to check their DMs
  * Continue the conversation in a DM

  You can further modify your Workflow depending on your desired behaviour.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get or Create a Conversation

### Get or Create a User

### Start DM Conversation from Comment

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

***

## Tags

You can read [event tags](/docs/studio/guides/advanced/event-properties#param-tags) to get information about an active Messenger conversation:

### Message ID

To get the Messenger ID of a message:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.message["messenger:id"]
```

### Recipient ID

To get the Messenger ID of the recipient:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.message["messenger:recipientId"]
```

### Sender ID

To get the Messenger ID of the sender:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.message["messenger:senderId"]
```

### Conversation ID

To get the Messenger ID of the conversation:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.conversation["messenger:id"]
```

### User ID

To get the Messenger ID of the user:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.user["messenger:id"]
```


# Mintlify
Source: https://botpress.com/docs/integrations/integration-guides/mintlify

Add a bot to Mintlify using the official integration.

<OpenInHub />

The official Mintlify integration allows your bot to create and manage [Mintlify agent](https://www.mintlify.com/docs/ai/agent) jobs.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Mintlify account](https://dashboard.mintlify.com/signup) with a [Pro or Custom plan](https://www.mintlify.com/pricing)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Mintlify** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see two fields:

    * **API key**
    * **Project ID**

    Leave these empty for now—you'll come back to them after getting your Mintlify credentials.
  </Step>

  <Step title="Get your Mintlify credentials">
    Next, get your Mintlify API key and project ID:

    1. [Log in to your Mintlify dashboard](https://dashboard.mintlify.com/login).
    2. In the left sidebar, go to **Settings** > **API Keys**.
    3. Copy and store your **Project ID**.
    4. Select **+ Create Admin API Key**, then copy the generated API key.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your Mintlify API key.
    2. In the integration's **Project ID** field, paste your Mintlify project ID.
    3. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your integration is ready. You can use the integration's [Cards](#cards) to interact with your Mintlify agent jobs.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Agent job

### Get Agent Job by ID

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="branch" type="string | null" />
  </Expandable>
</ResponseField>

### Get All Agent Jobs

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="allSessions" type="array">
      <Expandable title="array item properties">
        <ResponseField name="branch" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Notion
Source: https://botpress.com/docs/integrations/integration-guides/notion

Add a bot to Notion using the official integration.

<OpenInHub />

The Notion Integration with Botpress enables seamless integration to boost productivity, allowing interactions such as commenting on discussions or pages and database manipulations right from your Botpress bot.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Notion account](https://www.notion.so/signup) and [workspace](https://www.notion.so/onboarding)
    </Info>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Notion** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize Notion**.
      </Step>

      <Step>
        Follow the instructions to connect Botpress to your Notion account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual configuration">
    For advanced use cases, you can configure the integration manually using a Notion integration token.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Notion account](https://www.notion.so/signup) and [workspace](https://www.notion.so/onboarding)
    </Info>

    ### Step 1: Install the integration in Botpress

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **Notion** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select the drop-down and choose **Configure the integration using a Notion integration token**.
      </Step>

      <Step>
        You should see two fields:

        * **Internal Integration Secret**
        * **Webhook Verification Secret**

        Leave these empty for now—you'll come back to them after setting up the integration in Notion.
      </Step>
    </Steps>

    ### Step 2: Create an integration in Notion

    Next, create a corresponding integration in Notion:

    <Steps>
      <Step>
        Go to your [integrations page](https://www.notion.so/profile/integrations) in Notion.
      </Step>

      <Step>
        Select **New integration**.
      </Step>

      <Step>
        Enter an **Integration Name** and **Associated workspace** for the integration. Then, select **Save**.
      </Step>

      <Step>
        Select **Configure integration settings**.
      </Step>

      <Step>
        Under **Internal Integration Secret**, select **Show**, then **Copy**.
      </Step>

      <Step>
        Go back to the integration's configuration menu in Botpress. Then, paste the secret into the **Internal Integration Secret**.
      </Step>

      <Step>
        Select **Save Configuration**.
      </Step>
    </Steps>

    ### Step 3: Give access to pages and databases

    For your bot to interact with your Notion workspace, you need to manually specify which pages and databases it has access to:

    <Steps>
      <Step>
        In your Notion integration's settings, go to the **Access** tab.
      </Step>

      <Step>
        Select **Edit access**.
      </Step>

      <Step>
        Select the pages you want your bot to have access to. Then, select **Save**.
      </Step>
    </Steps>

    ### Step 4: Configure webhook events (optional)

    If you want to use the integration's [Triggers](#triggers) and have your bot respond to events in your Notion workspace, follow the steps below:

    <Steps>
      <Step>
        In the integration's configuration menu in Botpress, copy the webhook URL (starting with `https://webhook.botpress.cloud/`).
      </Step>

      <Step>
        In your Notion integration's settings, go to the **Webhooks** tab. Then, select **+ Create a subscription**.
      </Step>

      <Step>
        Paste the webhook URL you copied in the **Webhook URL** field.
      </Step>

      <Step>
        Under **Select the events to listen to**, select the following events:

        * **Page created**
        * **Page deleted**
        * **Comment created**
      </Step>

      <Step>
        Scroll down to the bottom of the page and select **Verify**.
      </Step>

      <Step>
        In Botpress, go to your bot's most recent [logs](/docs/get-started/manage-your-agent/inspect#logs). Copy the verification token sent from Notion.
      </Step>

      <Step>
        Go back to your Notion integration and paste the token in the **Verification token** field.
      </Step>

      <Step>
        Select **Verify subscription**.
      </Step>

      <Step>
        Finally, go back to the integration's **Configuration** menu in Botpress. Paste the verification token into the **Webhook Verification Secret** field.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Check>
  Your Notion integration is ready to use. You can use the integration's [Cards](#cards) or [Triggers](#triggers) to interact with your Notion workspace.
</Check>

***

## Cards

<Note>
  To use certain Cards, you might need to identify elements by their IDs. You can get page and database IDs:

  * From their URL while viewing them in your browser
  * By choosing **Copy Link** from their options menu
</Note>

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add Comment

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="parentType" type="enum<string>">
      Available options: `page`, `block`, `discussion`
    </ResponseField>
  </Expandable>
</ResponseField>

### Append Blocks to Page

### Create Page

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="parentType" type="enum<string>">
      Available options: `data source`, `page`
    </ResponseField>
  </Expandable>
</ResponseField>

### Delete Block

### Get Data Source

### Get Database

### Get Page

### Get Page Content

### Search by Title

### Update Page Properties

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Aggregate File Changes

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="modifiedItems" type="object">
      <Expandable>
        <ResponseField name="created" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="updated" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="deleted" type="array">
          <Tabs>
            <Tab title="file">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>

            <Tab title="folder">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>
          </Tabs>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Comment Created

### File Created

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Deleted

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### File Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="file" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Folder Deleted Recursive

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="folder" type="object">
      <Expandable>
        <ResponseField name="type" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Pipedrive
Source: https://botpress.com/docs/integrations/integration-guides/pipedrive

Add a bot to Pipedrive using the official integration.

<OpenInHub />

The official Pipedrive integration allows your bot to create, update and search for Pipedrive contacts.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Pipedrive account](https://www.pipedrive.com/en/register)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Pipedrive** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API Key**. Leave it empty for now—you'll come back to it after creating your Pipedrive API key.
  </Step>

  <Step title="Create a Pipedrive API key">
    Next, create a Pipedrive API key:

    1. [Log in to Pipedrive](https://app.pipedrive.com/auth/login).

       <Warning>
         The API key will inherit the permissions of whatever user you're logging in as. Because of this, we recommend using a dedicated Pipedrive user account for the API key.

         This makes it easier to maintain the right permissions for the integration, or to rotate the key if it becomes compromised.
       </Warning>

    2. Open the **My Account** menu in the upper-right corner, then select **Personal preferences**.

    3. Navigate to the **API** tab. You should see your personal API key—copy it.

    <Tip>
      If you don't have an API key, select **Generate new token**.
    </Tip>
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API Key** field, paste your Pipedrive API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Pipedrive integration is ready. You can use the integration's [Cards](#cards) to interact with your Pipedrive contacts.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add Person

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="id" type="number" />

        <ResponseField name="name" type="string" />

        <ResponseField name="first_name" type="string" />

        <ResponseField name="last_name" type="string" />

        <ResponseField name="owner_id" type="number" />

        <ResponseField name="org_id" type="number | null" />

        <ResponseField name="add_time" type="string | null" />

        <ResponseField name="update_time" type="string | null" />

        <ResponseField name="emails" type="array">
          <Expandable title="array item properties">
            <ResponseField name="value" type="string" />

            <ResponseField name="primary" type="boolean" />

            <ResponseField name="label" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="phones" type="array">
          <Expandable title="array item properties">
            <ResponseField name="value" type="string" />

            <ResponseField name="primary" type="boolean" />

            <ResponseField name="label" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="is_deleted" type="boolean" />

        <ResponseField name="visible_to" type="number" />

        <ResponseField name="label_ids" type="array" />

        <ResponseField name="picture_id" type="number | null" />

        <ResponseField name="postal_address" type="object">
          <Expandable>
            <ResponseField name="street_number" type="string" />

            <ResponseField name="route" type="string" />

            <ResponseField name="sublocality" type="string" />

            <ResponseField name="locality" type="string" />

            <ResponseField name="admin_area_level_1" type="string" />

            <ResponseField name="admin_area_level_2" type="string" />

            <ResponseField name="country" type="string" />

            <ResponseField name="postal_code" type="string" />

            <ResponseField name="formatted_address" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="notes" type="string" />

        <ResponseField name="im" type="array">
          <Expandable title="array item properties">
            <ResponseField name="protocol" type="string" />

            <ResponseField name="value" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="birthday" type="string" />

        <ResponseField name="job_title" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Find Person

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="fields" type="enum<string>">
      Available options: `custom_fields`, `email`, `notes`, `phone`, `name`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="items" type="array">
          <Expandable title="array item properties">
            <ResponseField name="result_score" type="number" />

            <ResponseField name="item" type="object">
              <Expandable>
                <ResponseField name="id" type="number" />

                <ResponseField name="type" type="string" />

                <ResponseField name="name" type="string" />

                <ResponseField name="phones" type="array" />

                <ResponseField name="emails" type="array" />

                <ResponseField name="visible_to" type="number" />

                <ResponseField name="owner" type="object">
                  <Expandable>
                    <ResponseField name="id" type="number" />

                    <ResponseField name="name" type="string" />

                    <ResponseField name="email" type="string" />
                  </Expandable>
                </ResponseField>

                <ResponseField name="organization" type="object">
                  <Expandable>
                    <ResponseField name="id" type="number" />

                    <ResponseField name="name" type="string" />
                  </Expandable>
                </ResponseField>

                <ResponseField name="custom_fields" type="array" />

                <ResponseField name="notes" type="array" />
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="additional_data" type="string" />
  </Expandable>
</ResponseField>

### Update Person

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="id" type="number" />

        <ResponseField name="name" type="string" />

        <ResponseField name="first_name" type="string" />

        <ResponseField name="last_name" type="string" />

        <ResponseField name="owner_id" type="number" />

        <ResponseField name="org_id" type="number | null" />

        <ResponseField name="add_time" type="string | null" />

        <ResponseField name="update_time" type="string | null" />

        <ResponseField name="emails" type="array">
          <Expandable title="array item properties">
            <ResponseField name="value" type="string" />

            <ResponseField name="primary" type="boolean" />

            <ResponseField name="label" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="phones" type="array">
          <Expandable title="array item properties">
            <ResponseField name="value" type="string" />

            <ResponseField name="primary" type="boolean" />

            <ResponseField name="label" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="is_deleted" type="boolean" />

        <ResponseField name="visible_to" type="number" />

        <ResponseField name="label_ids" type="array" />

        <ResponseField name="picture_id" type="number | null" />

        <ResponseField name="postal_address" type="object">
          <Expandable>
            <ResponseField name="street_number" type="string" />

            <ResponseField name="route" type="string" />

            <ResponseField name="sublocality" type="string" />

            <ResponseField name="locality" type="string" />

            <ResponseField name="admin_area_level_1" type="string" />

            <ResponseField name="admin_area_level_2" type="string" />

            <ResponseField name="country" type="string" />

            <ResponseField name="postal_code" type="string" />

            <ResponseField name="formatted_address" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="notes" type="string" />

        <ResponseField name="im" type="array">
          <Expandable title="array item properties">
            <ResponseField name="protocol" type="string" />

            <ResponseField name="value" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="birthday" type="string" />

        <ResponseField name="job_title" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Troubleshooting

If you run into errors when using the integration's Cards, check out your bot's [Logs](/docs/studio/concepts/debugger-logs-json#logs) and locate the error message:

<AccordionGroup>
  <Accordion title="(Field) must be (data type)">
    Usually this means:

    * Not all the Card's required input fields were filled
    * One of the fields contained invalid data

    Double-check the input fields and try again. If you're letting your bot fill the input fields automatically based on context, make sure it's providing input that conforms to the Card's expected format.
  </Accordion>

  <Accordion title="An unexpected error occurred">
    This could mean a few things:

    * Your Pipedrive API key may have been revoked. [Create a new one](#setup) and update your bot's configuration.
    * Your API key may belong to a user that [doesn't have permission to perform the Card's action](https://support.pipedrive.com/en/article/permission-sets). We recommend creating a dedicated Pipedrive user account for the API key and ensuring it has the necessary permissions for the Cards you want to use.
    * You may have exceeded Pipedrive's API rate limit. Wait and retry according to [Pipedrive's documentation](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting).
  </Accordion>
</AccordionGroup>

<Tip>
  You can also consult Pipedrive's [error code reference](https://pipedrive.readme.io/docs/error-codes-and-troubleshooting-for-messaging-app-extension#expected-error-codes-for-the-messaging-extensions-endpoints) for further troubleshooting.
</Tip>


# Apify (Advanced Website Crawler)
Source: https://botpress.com/docs/integrations/integration-guides/plus-apify

Add a bot to Apify using the official integration.

<OpenInHub />

The official Apify integration connects your bot to Apify, an advanced website crawling platform. It allows your bot to manage your Apify crawler runs.

This integration is useful if you need more powerful crawling than Studio's [default web crawler](/docs/studio/concepts/knowledge-base/add-sources#websites) provides.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * An [Apify account](https://console.apify.com/sign-up)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Apify** integration. In the Hub, it's listed as **Advanced Website Crawler**.
    3. Select **Install Integration**.

    In the **Configuration** menu, you should see two fields:

    * **API Token**
    * **Webhook Secret** (Optional)

    Leave these empty for now—you'll come back to them after completing the setup in your Apify account.
  </Step>

  <Step title="Get your Apify API token">
    Next, get your Apify API token:

    1. [Log in to your Apify account](https://console.apify.com/sign-in).
    2. Select **Settings** from the bottom-left corner.
    3. Go to **API & Integrations**.
    4. Under **Personal API tokens**, copy the API token—it should start with `apify_api_`.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can configure the integration in Botpress:

    1. In the integration's **API Token** field, paste your Apify API token.
    2. Select **Save Configuration**.
    3. Copy the integration's webhook URL (starting with `https://webhook.botpress.cloud`).
  </Step>

  <Step title="Configure your Apify webhook">
    Finally, create a Webhook integration:

    1. Go to the [Website Content Crawler](https://apify.com/apify/website-content-crawler) in the Apify Store.
    2. Select **Try for Free**, then **Save & Start**. This opens the Actor's configuration page.
    3. Select the **Integrations** tab (on the Actor's page, not the left sidebar).
    4. Scroll down to **Generic integrations**, then select **HTTP webhook**.
    5. Under **Start when**, select the following options:

       * Run succeeded
       * Run created
       * Run failed
       * Run timed out
       * Run resurrected
       * Run aborted
    6. Paste your Botpress webhook URL into the **URL** field.
    7. Select **Save**.
  </Step>
</Steps>

<Check>
  Your Apify integration is ready. You can use the integration's [Cards](#cards) and [Triggers](#triggers) to manage your Apify crawler runs.
</Check>

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get Run Status

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="runId" type="string" />

        <ResponseField name="status" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Start Crawler Run

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="htmlTransformer" type="enum<string>">
      Available options: `readableTextIfPossible`, `readableText`, `extractus`, `none`
    </ResponseField>

    <ResponseField name="crawlerType" type="enum<string>">
      Available options: `playwright:adaptive`, `playwright:firefox`, `cheerio`, `jsdom`, `playwright:chrome`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="runId" type="string" />

        <ResponseField name="status" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Sync Run Results

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="runId" type="string" />

        <ResponseField name="datasetId" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Crawler Completed

### Crawler Failed


# Email Notifier
Source: https://botpress.com/docs/integrations/integration-guides/plus-email-notifier

Send emails from your bot.

<OpenInHub />

The official Email Notifier integration allows your bot to send emails from a generic email address.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Email Notifier** integration, then select **Install Integration**.
  </Step>

  <Step title="Add the Send Mail Card">
    Now, just add the [Send Email](#send-email) Card anywhere in your [Workflow](/docs/studio/concepts/workflows) and fill out the required fields. The email will send from a generic Botpress domain (`noreply@bp-mailer.com`).

    <Tip>
      You can use the [Email Sent](#email-sent) Trigger to confirm that the email was sent and run any follow-up automations.
    </Tip>
  </Step>
</Steps>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Send Email

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="successful" type="array">
      <Expandable title="array item properties">
        <ResponseField name="email" type="string (email)" />

        <ResponseField name="messageId" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="failed" type="array">
      <Expandable title="array item properties">
        <ResponseField name="email" type="string (email)" />

        <ResponseField name="error" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Email Sent


# Google Analytics
Source: https://botpress.com/docs/integrations/integration-guides/plus-google-analytics

Add a bot to Google Analytics using the official integration.

<OpenInHub />

The official Google Analytics integration allows your bot to interact with your GA4 data stream.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Google Analytics](https://analytics.google.com) account
  * A [GA4 property](https://support.google.com/analytics/answer/10089681?hl=en\&ref_topic=14089939\&sjid=6192877767184430915-NC) with at least one [data stream](https://support.google.com/analytics/answer/9303323?hl=en#streams\&zippy=%2Cin-this-article)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Google Analytics** integration.
    3. Select **Install Integration**.

    In the **Configuration** menu, you should see two fields:

    * **Measurement ID**: The Measurement ID for your Google Analytics 4 property
    * **API secret**: The API Secret for your Google Analytics 4 property

    Leave these empty for now—you'll come back to them after completing the setup in Google Analytics.
  </Step>

  <Step title="Get your measurement ID">
    Next, get your GA4 measurement ID:

    1. Log in to [Google Analytics](https://analytics.google.com).
    2. In the bottom-left corner, select **Admin**.
    3. Under **Property settings > Data collection and modification**, select **Data streams**.
    4. Select the data stream you want to interact with.
    5. Copy its **Measurement ID**. It should start with `G-`.
  </Step>

  <Step title="Get your API secret">
    Now, get your GA4 API secret:

    1. In the same data stream menu, select **Measurement protocal API secrets**.
    2. If you haven't reviewed the terms yet, select **Review terms**.
    3. Select **Create** and give the secret a nickname.
    4. Copy the secret's value.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the **Measurement ID** field, paste the ID you copied earlier.
    2. In the **API secret** field, paste the secret you copied earlier.
    3. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Google Analytics integration is ready. You can use the integration's [Cards](#cards) to interact with your data stream.
</Check>

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Track Event

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Track Node

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Update User Profile

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>


# Persat
Source: https://botpress.com/docs/integrations/integration-guides/plus-persat

Add a bot to Persat using the official integration.

<OpenInHub />

The official Persat integration allows your bot to interact with your Persat clients.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Persat account](https://www.persat.com.ar/sesion)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Persat** integration, then select **Install Integration**.

    In the **Configuration** menu, you should see one field: **API Key**

    Leave this empty for now—you'll come back to it after creating your Persat API key.
  </Step>

  <Step title="Create a Persat API key">
    Next, create a Persat API key:

    1. [Log in to your Persat account](https://www.persat.com.ar/sesion).
    2. Select your avatar in the upper-right corner, then select **Integraciones y Partners**.
    3. Select **Integra con nuestra API**, then go to **API keys**.
    4. Create and copy a new API key. When prompted to configure its access level, make sure you select **Acceso Total** (complete access).
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API key** field, paste your Persat API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Persat integration is ready. You can use its [Cards](#cards) to interact with your Persat clients.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create Client

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="company_name" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="custom_fields" type="object" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Client

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="uid_client" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="custom_fields" type="object" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Submit Form

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="uid_client" type="string" />

    <ResponseField name="df_data" type="object">
      <Expandable>
        <ResponseField name="schema_id" type="number" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="_id" type="string" />

        <ResponseField name="created" type="string" />

        <ResponseField name="created_by_user_name" type="string" />

        <ResponseField name="created_by_user_id" type="number" />

        <ResponseField name="client" type="object">
          <Expandable>
            <ResponseField name="id" type="number" />

            <ResponseField name="name" type="string" />

            <ResponseField name="uid_client" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="df_data" type="object">
          <Expandable>
            <ResponseField name="schema_id" type="number" />

            <ResponseField name="results" type="object">
              <Expandable>
                <ResponseField name="last_updated" type="string" />
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="state" type="object">
          <Expandable>
            <ResponseField name="color" type="string" />

            <ResponseField name="deleted" type="boolean" />

            <ResponseField name="id" type="number" />

            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Update Client

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="success" type="boolean" />

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="custom_fields" type="object" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Slack
Source: https://botpress.com/docs/integrations/integration-guides/slack

Add a bot to Slack using the official integration.

<OpenInHub />

The official Slack integration allows members of your Slack workspace to chat with your bot via a Slack app.

## Setup

<Tabs>
  <Tab title="Automatic configuration">
    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Slack workspace](https://slack.com/get-started?entry_point=help_center#/createnew)
    </Info>

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Slack** integration, then select **Install Integration**.
    3. In the **Configuration** menu, select **Authorize Slack**.
    4. Follow the instructions to connect Botpress to your Slack account.
  </Tab>

  <Tab title="Manual configuration">
    For advanced use cases, you can use your own Slack app with our integration.

    <Info>
      You will need:

      * A [published bot](/docs/get-started/quick-start)
      * A [Slack workspace](https://slack.com/get-started?entry_point=help_center#/createnew)
    </Info>

    <Steps>
      <Step title="Install the Slack integration in Botpress">
        1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
        2. Search for the **Slack** integration, then select **Install Integration**.
        3. In the **Configuration** menu, select the drop-down menu, then select **Configure by manually supplying the refresh token and signing secret**.
        4. Leave the configuration fields empty for now—you'll come back to them after you've setup your Slack app.
      </Step>

      <Step title="Create a Slack app">
        Next, you'll need to create a Slack app for your bot:

        1. Open a new tab and go to your [Slack API portal](https://api.slack.com/apps). Login if you haven't already.
        2. Select **Create New App**, then **From a manifest**.
        3. Select the workspace you want to connect your bot to.
        4. Erase everything in the field, then paste this code:

        <CodeGroup>
          ```json JSON [expandable] lines theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
          {
              "display_information": {
                  "name": "Bot (powered by Botpress)"
              },
              "features": {
                  "bot_user": {
                      "display_name": "Bot (powered by Botpress)",
                      "always_online": false
                  }
              },
              "oauth_config": {
                  "redirect_urls": [
                      "https://webhook.botpress.cloud/oauth"
                  ],
                  "scopes": {
                      "bot": [
                          "channels:history",
                          "channels:manage",
                          "channels:read",
                          "chat:write",
                          "groups:history",
                          "groups:read",
                          "groups:write",
                          "im:write",
                          "im:read",
                          "im:history",
                          "mpim:history",
                          "mpim:read",
                          "mpim:write",
                          "reactions:read",
                          "reactions:write",
                          "team:read",
                          "users.profile:read",
                          "users:read",
                          "users:read.email"
                      ]
                  }
              },
              "settings": {
                  "event_subscriptions": {
                      "request_url": "https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                      "bot_events": [
                          "member_joined_channel",
                          "member_left_channel",
                          "message.channels",
                          "message.groups",
                          "message.im",
                          "message.mpim",
                          "reaction_added",
                          "reaction_removed",
                          "team_join"
                      ]
                  },
                  "org_deploy_enabled": false,
                  "socket_mode_enabled": false,
                  "token_rotation_enabled": false
              }
          }
          ```

          ```yaml YAML [expandable] lines theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
          display_information:
            name: Bot (powered by Botpress)
          features:
            bot_user:
              display_name: Bot (powered by Botpress)
              always_online: false
          oauth_config:
            redirect_urls:
              - https://webhook.botpress.cloud/oauth
            scopes:
              bot:
                - channels:history
                - channels:manage
                - channels:read
                - chat:write
                - groups:history
                - groups:read
                - groups:write
                - im:write
                - im:read
                - im:history
                - mpim:history
                - mpim:read
                - mpim:write
                - reactions:read
                - reactions:write
                - team:read
                - users.profile:read
                - users:read
                - users:read.email
          settings:
            event_subscriptions:
              request_url: https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
              bot_events:
                - member_joined_channel
                - member_left_channel
                - message.channels
                - message.groups
                - message.im
                - message.mpim
                - reaction_added
                - reaction_removed
                - team_join
            org_deploy_enabled: false
            socket_mode_enabled: false
            token_rotation_enabled: false
          ```
        </CodeGroup>

        5. Select **Create**. This creates a Slack app with all the necessary scopes and subscriptions for the Botpress Slack integration.
      </Step>

      <Step title="Install the app to your workspace">
        Next, you need to install the app to your Slack workspace and enable token rotation:

        1. Navigate to **OAuth and Permissions** in the left navigation bar of your Slack app's settings.
        2. Under OAuth Tokens, select **Install to (your workspace name)**, then follow the on-screen instructions to authorize the app.

        <Warning>
          Make sure you follow this step before moving on—otherwise, you won't be able to install the app to your workspace.
        </Warning>

        3. Scroll up to **Advanced token security via token rotation**, then select **Opt In**.
      </Step>

      <Step title="Configure the integration in Botpress">
        Now you can use your app's credentials to fill in the configuration fields from [Step 1](#step-1-install-the-slack-integration-in-botpress):

        <AccordionGroup>
          <Accordion title="Slack Refresh Token or Bot Token">
            1. Navigate to **OAuth & Permissions** in the left navigation bar of your Slack app's settings.
            2. Copy the **Bot User OAuth Token**.
            3. Paste it into the **Slack Refresh Token or Bot Token** field.
          </Accordion>

          <Accordion title="Slack Client ID">
            1. Navigate to **Basic Information** in the left navigation bar of your Slack app's settings.
            2. Copy the **Client ID**.
            3. Paste into the **Slack Client ID** field.
          </Accordion>

          <Accordion title="Slack Client Secret">
            1. Navigate to **Basic Information** in the left navigation bar of your Slack app's settings.
            2. Copy the **Client secret**.
            3. Paste into the **Slack Client Secret** field.
          </Accordion>

          <Accordion title="Slack Signing Secret">
            1. Navigate to **Basic Information** in the left navigation bar of your Slack app's settings.
            2. Copy the **Signing secret**.
            3. Paste into the **Slack Signing Secret** field.
          </Accordion>
        </AccordionGroup>

        When all the fields have been filled in, scroll down and select **Save Configuration**. This automatically activates the integration.
      </Step>

      <Step title="Add the integration's webhook URL">
        All you need to do now is add the integration's webhook URL to your Slack app:

        1. Scroll up and copy the webhook URL at the top of the integration's **Configuration** menu. It should start with `webhook.botpress.cloud`.
        2. Go back to your Slack app's settings. Navigate to the **Event Subscriptions** section.
        3. In the **Request URL** field, erase the placeholder webhook URL and paste your actual webhook URL.
        4. Select **Save Changes** at the bottom of the page.
      </Step>
    </Steps>

    <Check>
      Your Slack integration is ready. Within your Slack workspace, you can search for the app and add it to any channel—it should respond as your bot.
    </Check>
  </Tab>
</Tabs>

***

## Options

The Slack integration's **Configuration** menu offers a few additional options:

### Custom display name / avatar

* Fill in the **Bot name** field to display a custom name as the sender in Slack conversations.
* Fill in the **Bot avatar URL** field to set a custom image as the bot's Slack avatar.

<Note>
  The image should be square, at least 512x512 pixels, and no larger than 1024x1024 pixels. The URL must be publicly accessible. Supported formats include GIF, PNG, JPG, JPEG, HEIC, and HEIF.
</Note>

### Typing indicator emoji

When the **Typing indicator emoji** option is enabled, the bot will [react](https://www.google.com/url?sa=t\&source=web\&rct=j\&opi=89978449\&url=https://slack.com/help/articles/202931348-Use-emoji-and-reactions\&ved=2ahUKEwjkjonOtueOAxXug4kEHWXTNBsQFnoECBcQAQ\&usg=AOvVaw0_PwUudKr3nwqdIQhPpFza) to incoming messages with an emoji to indicate that it's processing the message.

### Reply threading

When the **Reply Threading Enabled** option is enabled, the bot will reply to incoming messages in [threads](https://slack.com/help/articles/115000769927-Use-threads-to-organize-discussions).

If you want the bot to only reply in a thread when [mentioned](https://slack.com/help/articles/205240127-Use-mentions-in-Slack), enable the **Require Bot Mention for Reply Threading** option.

## Limitations

Here are some limitations with the Slack integration:

### API rate limits

Standard Slack API limits apply to the Slack integration in Botpress. These include rate limits, message size restrictions, and other constraints imposed by the Slack platform. Ensure that your bot adheres to these limits to maintain optimal performance and reliability.

<Note>
  For more information, check out the [Slack API documentation](https://api.slack.com/apis/rate-limits).
</Note>

### Rich text processing

Slack uses a proprietary markup language, [mrkdwn](https://api.slack.com/reference/surfaces/formatting#lists), to format rich text in messages. Since Botpress uses [standard Markdown](https://www.markdownguide.org/cheat-sheet/) for rich text, we convert incoming `mrkdwn` messages from Slack to Markdown. This is to ensure that:

* Studio's interface can read them properly
* Botpress' AI inference engine can understand them

However, any outgoing AI-generated messages your bot sends to the Slack integration will still be rendered in Markdown by default. This means **rich text messages from your bot may not be rendered properly in Slack** without additional processing.

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add Reaction

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Find Target

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="channel" type="enum<string>">
      Available options: `dm`, `channel`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="targets" type="array">
      <Expandable title="array item properties">
        <ResponseField name="channel" type="enum<string>">
          Available options: `dm`, `channel`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get Channels Info

### Get or Create a Conversation

### Get User Profile

### Retrieve Message

### Sync Members

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### Update Channel Topic

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Member Joined Channel

### Member Joined Workspace

### Member Left Channel

### Reaction Added

### Reaction Removed

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="targets" type="object">
      <Expandable>
        <ResponseField name="dm" type="object" />

        <ResponseField name="channel" type="object" />

        <ResponseField name="thread" type="object" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Workflow Webhook

***

## Tags

You can read [event tags](/docs/studio/guides/advanced/event-properties#param-tags) to get information about an active Slack conversation:

### Slack conversation ID

To get the Slack conversation ID:

`event.tags.conversation["slack:id"]`

### Slack thread ID

To get the Slack conversation thread ID (if it's a thread):

`event.tags.conversation["slack:thread"]`

### Slack user ID

To get the Slack user ID:

`event.tags.user["slack:id"]`

### Slack message ID

To get the Slack message ID:

`event.tags.message["slack:id"]`


# Sunshine Conversations
Source: https://botpress.com/docs/integrations/integration-guides/sunshine-conversations/introduction



<OpenInHub />

<img />

## Prerequisites

* A [Smooch app](https://app.smooch.io) with a channel configured
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setup in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Sunshine Conversations integration then click on the "Install to Bot" button, now go back to your bot settings.

The Sunshine Conversations integration has the following settings:

* **Enabled**: Whether Botpress will communicate with this channel
* **Webhook URL**: The URL for receiving data in Botpress
* **App ID**: The App ID of your bot in Azure
* **Key ID**: The Key ID of your bot in Azure
* **Key Secret**: The Key Secret of your bot in Azure
* **Webhook Secret**: The Webhook Secret of your bot in Azure

## Setup in Sunshine Conversations

### Smooch App

1. On the Smooch [home page](https://app.smooch.io/), click on **Create new app.**
2. Enter a name for your app and click **Create App**
3. Connect a channel to your app (Telegram, WhatsApp, or any other listed channel)
4. You should see a channel in the **Overview** section of your app

## Configuration

### App ID

The smooch channel needs the app id to identify the smooch app when making API calls

1. Go to the **Settings** section of your app
2. You should see an **App ID** section if you scroll down. Copy paste this value to the **App ID** channel configuration

### Key ID and Key Secret

The key id and secret are needed to authenticate API calls to Smooch

1. At the bottom of to the **Settings** section of your app, click **Generate API key**
2. Copy paste the id (the one that starts with `app_`) in the **Key ID** channel configuration
3. Copy paste the secret in the **Key Secret** configuration

### Webhook Secret

The webhook secret is needed to validate webhooks requests. You get a webhook secret for each webhook integration you create

1. Go to the **Integration** section of your app
2. In the **API & Webhooks** section, click on **Webhooks**
3. Click **Connect**, then **Create a webhook**
4. Paste the Webhook URL provided in Botpress
5. Select `v2` as your webhook version
6. Select **Conversation message** and **Postbacks** in the basic triggers
7. Click **Create Webhook**. You will see the webhook you created in the table, and the secret in the last column
8. Copy paste the webhook secret in the **Webhook Secret** channel configuration

### Save Configuration

Channel configuration is complete, you can now click **Save**

That's it, you may now start chatting with your bot on Sunshine Conversations!

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get or Create a Conversation

### Get or Create a User


# Zendesk Messaging
Source: https://botpress.com/docs/integrations/integration-guides/sunshine-conversations/zendesk-messaging



<OpenInHub />

<img />

You can also use the Sunshine Conversations integration to connect Botpress to Zendesk Messaging.

## Prerequisites

* A [Zendesk Support Professional plan account](https://www.zendesk.com.br/pricing/support) with Zendesk Messaging enabled to the desired channels
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setup in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Sunshine Conversations integration then click on the "Install to Bot" button, now go back to your bot settings.

The Sunshine Conversations integration has the following settings:

* **Enabled**: Whether Botpress will communicate with this channel
* **Webhook URL**: The URL for receiving data in Botpress (Copy this)
* **App ID**: The App ID of your Zendesk Conversation API Credentials
* **Key ID**: The Key ID of your Zendesk Conversation API Credentials
* **Key Secret**: The Key Secret of your Zendesk Conversation API Credentials
* **Webhook Secret**: The Webhook Secret of your Zendesk Conversation Integration Webhook

<img />

## Setup in Zendesk

### Configure the Webhook

1. Open your Zendesk Admin Center.

<img />

2. Click on **Apps and Integrations** and **Conversations Integrations**

<img />

3. Give any name and put the **webhook URL** that you copied from Botpress.

<img />

4. Also select **Conversation message** and **Postbacks** on **Webhook subscriptions**.
5. Click **Save** at the bottom right corner.
6. Copy the **Shared Secret** and past on the Botpress Integration Configuration page at **Webhook Secret**

<img />

<br />

<img />

### Configure the API Credentials

1. Click on **Apps and Integrations** view and **Conversation API**

<img />

2. Click on **Create API key** and give it any name, then **Next**.
3. Copy **App ID**, **Key ID**, **Secret key** and put them on the associated field on the integration configuration.

<img />

<br />

<img />

### Save Configuration

Channel configuration is complete, you can now click **Save**

That's it, you may now start chatting with your bot on any channel from Zendesk Channels!

OBS: Please ensure that you enabled Zendesk Messaging for the required Zendesk Channel.


# Microsoft Teams
Source: https://botpress.com/docs/integrations/integration-guides/teams

Add your bot to Teams using the official integration.

<OpenInHub />

The Microsoft Teams integration allows your bot to chat with members of your Teams workspace.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Microsoft 365](https://www.office.com/) business account
  * A [Microsoft Azure](https://azure.microsoft.com/en-ca) account that uses the same email address as your Microsoft 365 account
</Info>

### Step 1: Create an Azure app registration

First, create an Azure app registration:

1. Log in to your  [Azure portal](https://portal.azure.com/).
2. Using the search bar, go to the [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) page.
3. Select **New registration** and fill in the required fields.

<Note>
  In the **Supported account types** section, choose the account type that's most appropriate for your use case—we support both [single tenant](https://learn.microsoft.com/en-us/security/zero-trust/develop/identity-supported-account-types#accounts-in-this-organizational-directory-only---single-tenant) (app available for your organization only) and [multitenant](https://learn.microsoft.com/en-us/security/zero-trust/develop/identity-supported-account-types#accounts-in-any-organizational-directory-only---multitenant) (public app) accounts.
</Note>

4. When you're done filling in the fields, select **Register**.

### Step 2: Setup in Botpress

Next, setup the integration in Botpress:

<Steps>
  <Step title="Install the integration in Botpress">
    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Microsoft Teams** integration, then select **Install Integration**.
  </Step>

  <Step title="Configure the integration in Botpress">
    To configure the integration, you need to create a webhook endpoint for the Teams integration. To do this, fill in the integration's **Configuration** fields using information from your Azure app:

    <AccordionGroup>
      <Accordion title="App ID">
        In the **Overview** section of your Azure app, copy the **Application (client) ID**. Then, paste it in the **App ID** field in Botpress.
      </Accordion>

      <Accordion title="App Password">
        1. In your Azure app's left sidebar, go to **Manage > Certificates & secrets**.
        2. Select **New client secret**.
        3. Set a description and expiry date for your secret.
        4. Copy the **Value** of the generated secret.
        5. Paste it in the **App Password** field in Botpress.
      </Accordion>

      <Accordion title="Tenant ID">
        In the **Overview** section of your Azure app, copy the **Directory (tenant) ID**. Then, paste it in the **Tenant ID** field in Botpress.
      </Accordion>
    </AccordionGroup>

    When you’ve filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
  </Step>
</Steps>

### Step 3: Create a Microsoft bot

<Steps>
  <Step title="Create a Microsoft bot">
    Now, you need to create a Microsoft bot. This bot communicates with your Botpress webhook URL to chat with members of your Teams workspace.

    1. In your Azure portal homepage, select **Create a resource**.
    2. Search for **Azure Bot**, then select **Create**.
    3. Scroll to the **Creation type** section, then select **Use existing app registration**.
    4. Fill in the **App ID** and **App tenant ID** fields with the same app ID and tenant ID you used to configure the integration in Botpress.
    5. Fill in the other required fields as necessary.
    6. Select **Review + Create**, then **Create**.
  </Step>

  <Step title="Connect your Botpress webhook">
    Now that you've created a Microsoft bot, you can use the integration's webhook to connect it to your Botpress bot:

    1. Wait for the bot's deployment to complete, then select **Go to resource**.
    2. In the left sidebar, go to **Settings > Configuration**.
    3. Paste the Botpress webhook URL (starting with `https://webhook.botpress.cloud/`) into the **Messaging endpoint** field. You can find the webhook URL in the integration's configuration menu.
    4. Select **Apply**.
    5. In the left sidebar, go to **Settings > Channels**.
    6. Scroll down and select **Microsoft Teams**.

    <Tip>
      Make sure you actually select the **Microsoft Teams** text, or the channel configuration menu won't open.
    </Tip>

    7. Agree to the terms of service, then select **Apply**.
  </Step>

  <Step title="Copy your Microsoft app ID">
    While you're still in the **Settings > Configuration** menu, copy your **Microsoft App ID**—you'll need it for the next steps.
  </Step>
</Steps>

### Step 4: Create a Teams app

Finally, create an app in your Teams developer portal:

<Steps>
  <Step title="Setup in Teams developer portal">
    First, create a new app:

    1. Log in to the [Teams developer portal](https://dev.teams.microsoft.com/home)
    2. Select **Create a new app** and enter a name for the app.
    3. In the left sidebar, go to the **Basic information** section.
    4. Fill in the required fields:

       * **Short name**
       * **Long name**
       * **Short description**
       * **Long description**
       * **Developer or company name**
       * **Website**
       * **Privacy policy**

    <Note>
      This information will be shown to members of your Teams workspace that chat with your bot.
    </Note>

    5. In the **Application (client ID)** field, paste the  **Microsoft App ID** you copied earlier.
    6. At the bottom of the screen, select **Save**.
  </Step>

  <Step title="Add Azure bot to Teams app">
    Next, add your Azure bot to the app:

    1. In the left sidebar, go to **App features** and select **Bot**.
    2. Select **Enter a bot ID**, then paste the **Microsoft App ID** again.
    3. Select the **Personal**, **Team** and **Group** chat scopes.
    4. Select **Save**.
  </Step>

  <Step title="Configure app permissions">
    In the left sidebar, go to **Permissions**. Select the following permissions for your app:

    <AccordionGroup>
      <Accordion title="Team permissions">
        Under **Application**:

        * `ChannelMessage.Read.Group`
        * `ChannelMessage.Send.Group`
        * `TeamsActivity.Send.Group`
      </Accordion>

      <Accordion title="Chat/meeting permissions">
        Under **Application**:

        * `ChatMessage.Read.Chat`
        * `ChatMessage.Send.Chat`
        * `ChatMessageReadReceipt.Read.Chat`
        * `TeamsActivity.Send.Chat`
        * `TeamsTab.ReadWrite.Chat`
        * `TeamsTab.Read.Chat`

        Under **Delegated**:

        * `LiveShareSession.ReadWrite.Chat`
      </Accordion>
    </AccordionGroup>

    When you're done, select **Save**.
  </Step>

  <Step title="Preview in Teams">
    Now, the bot should be fully configured. To test it:

    1. In the upper-right corner, select **Preview in Teams**.
    2. Once the bot has opened in Teams, select **Add**.
    3. After the bot is added, select **Open** to start chatting with it (or a channel to use it in).

    <Note>
      If you get a **Manifest parsing failed** error message, make sure you filled out all the required fields in your app's **Basic Information** section. The **Short description** and **Long description** fields are required, even though they're not marked as such.
    </Note>
  </Step>
</Steps>

<Note>
  At this point, the bot is only available for you to test. To make it available for anyone in your organization, follow the steps below.
</Note>

### Step 5: Publish the bot to your organization

Finally, you can publish your bot to make it available for anyone in your organization:

1. Go back to your app's menu in the [Teams developer portal](https://dev.teams.microsoft.com/home).
2. In the app's left sidebar, go to **Publish > Publish to org**.
3. Select **Get started**.

If you're an admin, your app will be approved automatically. Otherwise, your request to publish the app will need to be approved by an admin in the [Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps).

<Check>
  Your Teams integration is ready. Once the app has been approved, anyone in your Teams organization can [add it](https://support.microsoft.com/en-us/office/add-an-app-to-microsoft-teams-b2217706-f7ed-4e64-8e96-c413afd02f77) and chat with your bot.
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Manifest parsing failed">
    If you get a **Manifest parsing failed** error message when trying to [preview your bot in Teams](#create-a-teams-app), make sure you filled all the required fields in your app's **Basic Information** section.

    <Warning>
      The **Short description** and **Long description** fields are required, even though they're not marked as such.
    </Warning>
  </Accordion>

  <Accordion title="Can't preview app in Teams">
    If you're unable to [preview your bot in Teams](#create-a-teams-app), make sure you've enabled the policy to allow uploading custom apps:

    1. Log in to the [Teams admin center](https://admin.teams.microsoft.com).
    2. In the left sidebar, go to **Teams apps > Setup policies**.
    3. Select **Global (Org-wide default)**
    4. Make sure **Upload custom apps** is turned on.
    5. Select **Save**.

    <Warning>
      Changes to this policy might not take effect immediately. If you still can't access the preview in Teams even after updating, wait a while and try again.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Start DM Conversation


# Telegram
Source: https://botpress.com/docs/integrations/integration-guides/telegram

Add your bot to Telegram using the official integration.

<OpenInHub />

The official Telegram integration allows users to chat with your bot by messaging a Telegram bot.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Telegram account](https://web.telegram.org/a/)
</Info>

<Tip>
  Visual learner? Check out our [Telegram guide on YouTube](https://www.youtube.com/watch?v=KIYGklgl4bI\&t=554s).
</Tip>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **<Icon icon="boxes" /> Explore Hub** in the upper-right corner.
    2. Search for the **Telegram** integration.
    3. Select **Install Integration**.

    In the **Configuration** menu, you should see one field:

    * **Bot Token**

    Leave it empty for now—you'll come back to it after completing the setup in Telegram.
  </Step>

  <Step title="Create a bot in Telegram">
    To add your bot, you need to create a corresponding bot in Telegram. You can do this using Telegram's BotFather:

    1. Log in to [Telegram](https://web.telegram.org/a/).
    2. Start a conversation with [BotFather](https://telegram.me/BotFather) and follow the prompts to create your bot.
    3. Copy your bot's access token.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **Bot Token** field, paste your Telegram bot's access token.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your Telegram integration is ready—users can now chat with your Botpress bot by messaging your Telegram bot. You can use the integration's [Cards](#cards) to manage the bot's typing indicators.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

## Tags

You can read [event tags](/docs/studio/guides/advanced/event-properties#param-tags) to get information about an active Telegram conversation:

### Telegram conversation ID

To get the Telegram conversation ID:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{{ event.tags.conversation["telegram:id"] }}
```

### Telegram user ID

To get the Telegram user ID:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{{ event.tags.user["telegram:id"] }}
```

### Telegram message ID

To get the Telegram message ID:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{{ event.tags.message["telegram:id"] }}
```


# Trello
Source: https://botpress.com/docs/integrations/integration-guides/trello



<OpenInHub />

<img />

This integration allows you to connect your Botpress bot with Trello, a leading project management platform. With this integration, you can easily manage your boards, lists and cards directly from your bot.

## Prerequisites

* A [Trello account](https://trello.com/)
* A board in Trello, with at least one list
* The ID of the list where cards will be created. Refer to [this article](https://community.atlassian.com/t5/Trello-questions/How-do-I-find-the-LIST-ID/qaq-p/2272862) to locate it.
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setup in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Trello integration then click on the "Install to Bot" button, now go back to your bot settings.

The Trello integration has the following settings:

* **Enabled**: Whether Botpress will communicate with Trello
* **Webhook URL**: The URL for receiving data in Botpress
* **API Key**: The API key for the Trello Power-Up
* **Token**: The token for the Trello Power-Up

## Setup in Trello

1. Visit the [Power-Ups Admin Page](https://trello.com/power-ups/admin) and click the **New** button to obtain the API key. Name the Power-Up as "Botpress Connector", fill in the email and author fields, then click **Create**.
2. Once the Power-Up is created, you will be redirected to API Key settings page, displayed below. Generate a new API key, then copy and paste this key into the **API Key** field in Botpress.

<img />

3. Click on the "Token" link (marked in the image below) and authorize the Power-Up access to your Trello account by selecting **Allow**.

<img />

4. After authorization, copy the displayed token and paste it into the **Token** field in Botpress.
5. Make sure the integration is enabled then press the button "Save configuration".

That's it! Now the Trello integration is operational and ready for use within your bot.

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Add card comment

### Create new card

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="completionStatus" type="enum<string>">
      Available options: `Complete`, `Incomplete`
    </ResponseField>
  </Expandable>
</ResponseField>

### Delete card

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

### Get all board members

### Get all boards

<ResponseField name="input" type="object">
  This Card has no input fields.
</ResponseField>

### Get all card members

### Get board by ID

### Get members by name

### Get boards by name

### Get card by ID

### Find cards by name

### Get cards in list

### Get list by ID

### Get lists by name

### Get lists in board

### Get member by ID or username

### Move card down

### Move card to another list

### Move card up

### Update card

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="lifecycleStatus" type="enum<string>">
      Available options: `Open`, `Archived`
    </ResponseField>

    <ResponseField name="completionStatus" type="enum<string>">
      Available options: `Complete`, `Incomplete`
    </ResponseField>

    <ResponseField name="dueDate" type="string | null" />
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Card Attachment Added

### Checklist Added To Card

### Card Label Added

### Member Added To Card

### Comment Created

### Card Created

### Checklist Item Created

### Card Attachment Removed

### Card Deleted

### Checklist Item Deleted

### Comment Deleted

### Card Label Removed

### Member Removed From Card

### Card Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="card" type="object">
      <Expandable>
        <ResponseField name="startDate" type="string | null" />

        <ResponseField name="dueDate" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="old" type="object">
      <Expandable>
        <ResponseField name="startDate" type="string | null" />

        <ResponseField name="dueDate" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Checklist Item Updated

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="checklistItem" type="object">
      <Expandable>
        <ResponseField name="dueDate" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="old" type="object">
      <Expandable>
        <ResponseField name="dueDate" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Checklist Item Completion Updated

### Comment Updated

### Card Votes Updated


# Twilio
Source: https://botpress.com/docs/integrations/integration-guides/twilio



<OpenInHub />

<img />

<Warning>
  Message Ordering

  Messages may occasionally be delivered out of order when sending multiple messages in sequence because of cellular carrier dependencies.
</Warning>

## Prerequisites

* A [Twilio](https://www.twilio.com/) account
* A Twilio phone number. Check out [this article](https://support.twilio.com/hc/en-us/articles/223135247-How-to-Search-for-and-Buy-a-Twilio-Phone-Number-from-Console) to learn how to get one.
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setup in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Twilio integration then click on the "Install to Bot" button, now go back to your bot.

The Twilio integration has the following settings:

* **Enabled**: Whether Botpress will communicate with Twilio

* **Webhook URL**: The URL for receiving data in Botpress

* **Account SID**: Your Twilio Account SID

* **Auth Token**: Your Twilio Auth Token

## Setup in Twilio

### Account SID and Auth Token

1. Go to you Twilio [console dashboard](https://console.twilio.com/?frameUrl=/console)
2. Scroll down and copy your Account SID and Auth Token from the **Project Info** section and paste them in the **Account SID** and **Auth Token** channel configurations

### Save Configuration

Channel configuration is complete, you can now click **Save**

## Webhook Configuration

To receive messages from Twilio, you will need to set up a webhook

1. Click on **Explore Products** in the left panel
2. Click on **Messaging**
3. Click on **Services** in the left panel
4. Click on your service (if you haven't already created your service, create a messaging service and add your phone as a sender)
5. Click on **Sender Pool** in the left panel
6. Click on your phone number
7. Scroll down the phone number settings page
8. Copy paste the webhook URL provided in the channel configuration UI to the **A Message Comes In** field

That's it! Now the Twilio integration is operational and ready for use within your bot.


# Viber
Source: https://botpress.com/docs/integrations/integration-guides/viber



<OpenInHub />

<img />

## Prerequisites

* A [Viber account](https://www.viber.com/)
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setup in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Viber integration then click on the "Install to Bot" button, now go back to your bot.

The Viber integration has the following settings:

* **Enabled**: Whether Botpress will communicate with Viber.
* **Webhook URL**: The URL for receiving data in Botpress. (You shall not be using it)
* **Auth Token**: The authentication token of your Viber bot.
* **Bot Name**: The name of your Viber bot.
* **Bot Avatar URL**: The URL of the avatar of your Viber bot.

<br />

## Setup in Viber

1. Visit the [Viber Admin panel](https://partners.viber.com/login/) and click on **Create a Bot Account**.
2. Fill in the required details. Bot Avatar, Account Name, URI, Category, Subcategory, Language, Account Description, Email Address and Location.
3. Copy the Authentication Token and paste it in the integration settings page in Botpress.
4. Add a Bot Name (required) and a Bot Avatar URL (optional).
5. Click **Save**.

That's it, you may now start chatting with your bot on Viber!


# Vonage
Source: https://botpress.com/docs/integrations/integration-guides/vonage



<OpenInHub />

<img />

## Prerequisites

* A [Vonage Account](https://dashboard.nexmo.com/sign-up)
* A [Vonage Application](https://dashboard.nexmo.com/applications/new)
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setup in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Vonage integration then click on the "Install to Bot" button, now go back to your bot.

## Setup in Vonage

### API credentials

1. Go to your [API Settings](https://dashboard.nexmo.com/settings).
2. Copy paste the API key to the **API Key** channel configuration
3. Copy paste the API secret from the **Account credentials** section to the **API Secret** channel configuration
4. Copy paste the signature secret from the **Signed webhooks** section to the **Signature Secret** channel configuration

### Save Configuration

Channel configuration is complete, you can now click **Save**

## Webhook Configuration

### Sandbox

You can use the Vonage sandbox to test your channel with WhatsApp

1. Check the **Use Testing API** box in your channel configuration
2. Go to your [Sandbox Settings](https://dashboard.nexmo.com/messages/sandbox)
3. Copy paste the webhook URL provided in the channel configuration UI to the **Inbound** and **Status** fields in the **Webhooks** section

That's it, you may now start chatting with your bot on Vonage!

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Get or create user

### Start proactive conversation

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="conversation" type="object">
      <Expandable>
        <ResponseField name="userId" type="string" />

        <ResponseField name="channelId" type="string" />

        <ResponseField name="channel" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Webhook
Source: https://botpress.com/docs/integrations/integration-guides/webhook

Integrate Botpress with other services using a webhook.

<OpenInHub />

Install this integration to generate a personalized [webhook](https://docs.webhook.site/index.html) that allows your bot to receive external updates.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
</Info>

### Install the integration

1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
2. Search for the **Webhook** integration, then select **Install Integration**.
3. Copy the generated webhook URL.

### Configure the integration

The integration has the following configuration options:

* **Secret** (Optional): A secret that must be sent with the request as a header called `x-bp-secret`. Leave empty to allow all requests without a secret.
* **Allowed Origins**: List of allowed origins for CORS. Leaving this field empty blocks all requests originating from a browser and only allows requests from a server.

## Send data to your webhook

You can make requests to your webhook from any environment that supports HTTP requests:

<CodeGroup>
  ```javascript JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import axios from 'axios'

  const webhookUrl = 'https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  const data = {
    "example": "example"
  }
  const headers = {
    'Content-Type': 'application/json',
    'x-bp-secret': 'your-secret' // Optional
  }
  await axios.post(webhookUrl, data, { headers })
  ```

  ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  curl -X POST \
    https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    -H 'Content-Type: application/json' \
    -H 'x-bp-secret: your-secret' \
    -d '{
      "example": "example"
    }'
  ```

  ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import requests
  import json

  webhook_url = 'https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  data = {
      "example": "example"
  }
  headers = {
      'Content-Type': 'application/json',
      'x-bp-secret': 'your-secret'  # Optional
  }

  response = requests.post(webhook_url, data=json.dumps(data), headers=headers)
  ```

  ```php PHP theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  <?php
  $webhookUrl = 'https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
  $data = json_encode([
      "example" => "example"
  ]);

  $headers = [
      'Content-Type: application/json',
      'x-bp-secret: your-secret'  // Optional
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $webhookUrl);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);
  ?>
  ```

  ```go Go theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
  )

  func main() {
      webhookUrl := "https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

      data := map[string]interface{}{
          "example": "example",
      }

      jsonData, _ := json.Marshal(data)

      req, _ := http.NewRequest("POST", webhookUrl, bytes.NewBuffer(jsonData))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("x-bp-secret", "your-secret") // Optional

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```

  ```java Java theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class WebhookExample {
      public static void main(String[] args) throws IOException, InterruptedException {
          String webhookUrl = "https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
          String jsonData = "{\"example\": \"example\"}";

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(webhookUrl))
              .header("Content-Type", "application/json")
              .header("x-bp-secret", "your-secret") // Optional
              .POST(HttpRequest.BodyPublishers.ofString(jsonData))
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());
      }
  }
  ```

  ```ruby Ruby theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  require 'net/http'
  require 'uri'
  require 'json'

  webhook_url = 'https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  data = {
    example: 'example'
  }

  uri = URI(webhook_url)
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Content-Type'] = 'application/json'
  request['x-bp-secret'] = 'your-secret'  # Optional
  request.body = data.to_json

  response = http.request(request)
  ```
</CodeGroup>

<Note>
  Webhooks don't return any data in the response body.
</Note>

## Use webhook data in Studio

<Tip>
  You can [test the webhook in the Studio's emulator](/docs/studio/concepts/triggers#test-a-trigger) to make sure you're handling requests properly.
</Tip>

To read data from a webhook request in the Studio:

1. In Botpress Studio, add the [Event](#event) Trigger to the Workflow you want to use the request's data in.
2. Connect any Nodes you want to the Trigger—they'll execute whenever the webhook receives an request.
3. Now, you can [read the event's payload](/docs/studio/guides/advanced/event-properties) to access information about the webhook request:

### Read the payload

Here's the structure of a webhook event's payload:

<ResponseField name="event.payload" type="object">
  Information about the webhook request.

  <Expandable>
    <ResponseField name="body" type="object">
      The body of the request—usually a JSON object. This contains the actual data sent to the webhook.
    </ResponseField>

    <ResponseField name="query" type="object">
      Any query parameters sent with the request. For example, if the request was made to this URL:

      `https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?param=value`

      the `query` property would look like this:

      ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      "query": {
        "param": "value",
      }
      ```
    </ResponseField>

    <ResponseField name="headers" type="object">
      The headers sent with the request.
    </ResponseField>

    <ResponseField name="path" type="string">
      The path of the request. For example, if the request was made to this URL:

      `https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/api/webhook/data`

      the `path` property would look like this:

      ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      "path": "/api/webhook/data"
      ```
    </ResponseField>
  </Expandable>
</ResponseField>

The contents of `event.payload` are overwritten as soon as the bot or the user sends a new message. If you need to access a webhook request's data later, consider storing it in a [variable](/docs/studio/concepts/variables/overview).

### Payload size limit

The maximum size for a Webhook payload is .

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Event

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="method" type="enum<string>">
      Available options: `GET`, `POST`
    </ResponseField>
  </Expandable>
</ResponseField>


# WhatsApp Setup
Source: https://botpress.com/docs/integrations/integration-guides/whatsapp/introduction

Add a bot to WhatsApp using the official integration.

<OpenInHub />

The official WhatsApp integration allows your users to chat with your bot by messaging a WhatsApp number.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      * A [published bot](https://botpress.com/docs/botpress-quickstart)
      * A [Facebook account](https://www.facebook.com/signup)
    </Info>

    <Tip>
      Visual learner?

      Check out our [WhatsApp Setup guide](https://www.youtube.com/watch?v=Fs6dIxgEKoY) on YouTube for a step-by-step video guide.
    </Tip>

    <Steps>
      <Step>
        In Botpress Studio, select **Explore Hub** in the upper-right corner.
      </Step>

      <Step>
        Search for the **WhatsApp** integration, then select **Install Integration**.
      </Step>

      <Step>
        In the **Configuration** menu, select **Authorize WhatsApp**.
      </Step>

      <Step>
        Follow the instructions to connect Botpress to your WhatsApp account.
      </Step>
    </Steps>

    <Note>
      Additional requirements:

      * While setting up your WhatsApp integration, we will ask you to create or select:

        * A [Facebook business page](https://www.facebook.com/business/help/1968057156746246?id=939256796236247)
        * A [WhatsApp business account](https://business.whatsapp.com)

      * After setup is complete, your business will undergo a [verification process by Meta](https://www.facebook.com/business/help/1095661473946872?id=180505742745347), the parent company of WhatsApp. This verification confirms the identity and eligibility of your business to use Meta's platforms.
    </Note>
  </Tab>

  <Tab title="Manual configuration">
    For advanced use cases, you can use your own Meta app with our integration.

    <Info>
      You will need:

      * A [Meta developer app](https://developers.facebook.com/apps/creation/) with the . Check out the [Meta developer documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started#set-up-developer-assets) to learn more about the setup process.
    </Info>

    ### Step 1: Install the integration in Botpress

    <Steps>
      <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
      <Step>Search for the **WhatsApp** integration, then select **Install Integration**.</Step>
      <Step>In the **Configuration** menu, open the drop-down menu and select **Manual Configuration**.</Step>
    </Steps>

    ### Step 2: Configure the integration

    Next, fill in the integration's configuration fields using information from your Meta app:

    <AccordionGroup>
      <Accordion title="Verify Token">
        Used by Meta to verify that you're the real owner of the provided webhook. Can be any alphanumeric string.
      </Accordion>

      <Accordion title="Access Token">
        <Steps>
          <Step>
            In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.

            <Note>
              If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
            </Note>
          </Step>

          <Step>
            Select a WhatsApp business portfolio (if you haven't already).
          </Step>

          <Step>
            Go to **API testing**.
          </Step>

          <Step>
            Select **Generate access token**, then copy the token.
          </Step>

          <Step>
            In Botpress, paste the token into the integration's **Access Token** configuration field.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Client Secret">
        <Steps>
          <Step>In your Meta App's left sidebar, expand the **App Settings** menu and select **Basic**.</Step>
          <Step>In the **App Secret** field,  select **Show**, then copy your secret.</Step>
          <Step>In Botpress, paste the secret into the integration's **Client Secret** configuration field.</Step>
        </Steps>
      </Accordion>

      <Accordion title="Default Bot Phone Number ID">
        <Steps>
          <Step>
            In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.

            <Note>
              If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
            </Note>
          </Step>

          <Step>
            Select a WhatsApp business portfolio (if you haven't already).
          </Step>

          <Step>
            Go to **API testing**.
          </Step>

          <Step>
            Under **Select a 'From' phone number**, copy the **Phone number ID**.
          </Step>

          <Step>
            In Botpress, paste the ID into the integration's **Default Bot Phone Number ID** configuration field.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="WABA ID (WhatsApp Business Account ID)">
        <Steps>
          <Step>
            In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.

            <Note>
              If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
            </Note>
          </Step>

          <Step>
            Select a WhatsApp business portfolio (if you haven't already).
          </Step>

          <Step>
            Go to **API testing**.
          </Step>

          <Step>
            Under **Select a 'From' phone number**, copy the **WhatsApp Business Account ID**.
          </Step>

          <Step>
            In Botpress, paste the ID into the integration's **WhatsApp Business Account ID** configuration field.
          </Step>
        </Steps>
      </Accordion>
    </AccordionGroup>

    When you've filled in all the fields, select **Save Configuration**. This will automatically enable your integration.

    ### Step 3: Add your webhook

    Now that you've enabled your integration, you can add your webhook to your Meta app's configuration:

    <Steps>
      <Step>In Botpress, copy the webhook URL and **Verify Token** from the integration's **Configuration** section.</Step>

      <Step>
        In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.

        <Note>
          If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
        </Note>
      </Step>

      <Step>
        Select a WhatsApp business portfolio (if you haven't already).
      </Step>

      <Step>Go to **Configuration**.</Step>
      <Step>Paste the webhook URL into the **Callback URL** field.</Step>
      <Step>Paste your **Verify Token** in the **Verify Token** field.</Step>

      <Step>
        Select **Verify and save**. Then, subscribe to the following webhook fields:

        * `message_template_components_update`
        * `message_template_quality_update`
        * `message_template_status_update`
        * `messages`
        * `template_category_update`
      </Step>
    </Steps>

    <Check>
      You've manually configured your WhatsApp integration!

      For more information, check out WhatsApp's guide on [getting started with Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started#send-test-message).
    </Check>
  </Tab>

  <Tab title="Playground">
    If you want to test your bot's behaviour in WhatsApp before going through the actual setup process, you can use the WhatsApp integration playground.

    <Info>
      You will need:

      * A [published bot](https://botpress.com/docs/botpress-quickstart)
      * A [WhatsApp account](https://web.whatsapp.com)
    </Info>

    <Steps>
      <Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
      <Step>Search for the **WhatsApp** integration, then select **Install Integration**.</Step>
      <Step>Select **Test your agent on WhatsApp**.</Step>
      <Step>Follow the instructions to set up the playground.</Step>
    </Steps>
  </Tab>
</Tabs>

***

## Cards

<Warning>
  Some of the integration's Cards use [WhatsApp message templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/) to send messages to users.

  In WhatsApp, these templates support both [named and positional parameters](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/#parameter-formats). However, the integration currently only supports positional parameters. This means you'll get an error if you try to provide named parameters in a Card's `conversation.templateVariablesJson` field.
</Warning>

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### List Message Templates

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="status" type="enum<string>">
      Available options: `APPROVED`, `PENDING`, `REJECTED`, `PAUSED`, `DISABLED`, `ARCHIVED`, `LIMIT_EXCEEDED`, `IN_APPEAL`
    </ResponseField>
  </Expandable>
</ResponseField>

### Send Template Message

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="conversation" type="object">
      <Expandable>
        <ResponseField name="templateButtonParams" type="array">
          <Tabs>
            <Tab title="url">
              <Expandable>
                <ResponseField name="type" type="string" />

                <ResponseField name="value" type="string" />
              </Expandable>
            </Tab>

            <Tab title="quick_reply">
              <Expandable>
                <ResponseField name="type" type="string" />

                <ResponseField name="payload" type="string" />
              </Expandable>
            </Tab>

            <Tab title="copy_code">
              <Expandable>
                <ResponseField name="type" type="string" />

                <ResponseField name="code" type="string" />
              </Expandable>
            </Tab>

            <Tab title="skip">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>
          </Tabs>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Start Conversation

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="conversation" type="object">
      <Expandable>
        <ResponseField name="templateButtonParams" type="array">
          <Tabs>
            <Tab title="url">
              <Expandable>
                <ResponseField name="type" type="string" />

                <ResponseField name="value" type="string" />
              </Expandable>
            </Tab>

            <Tab title="quick_reply">
              <Expandable>
                <ResponseField name="type" type="string" />

                <ResponseField name="payload" type="string" />
              </Expandable>
            </Tab>

            <Tab title="copy_code">
              <Expandable>
                <ResponseField name="type" type="string" />

                <ResponseField name="code" type="string" />
              </Expandable>
            </Tab>

            <Tab title="skip">
              <Expandable>
                <ResponseField name="type" type="string" />
              </Expandable>
            </Tab>
          </Tabs>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Message Delivered

<ResponseField name="payload" type="object">
  This Trigger has no payload.
</ResponseField>

### Message Failed

### Message Read

<ResponseField name="payload" type="object">
  This Trigger has no payload.
</ResponseField>

### Message Sent

<ResponseField name="payload" type="object">
  This Trigger has no payload.
</ResponseField>

### Message Template Components Update

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="buttons" type="array">
      <Expandable title="array item properties">
        <ResponseField name="button_type" type="enum<string>">
          Available options: `CATALOG`, `COPY_CODE`, `EXTENSION`, `FLOW`, `MPM`, `ORDER_DETAILS`, `OTP`, `PHONE_NUMBER`, `POSTBACK`, `REMINDER`, `SEND_LOCATION`, `SPM`, `QUICK_REPLY`, `URL`, `VOICE_CALL`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Message Template Quality Update

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="previous_quality_score" type="enum<string>">
      Available options: `GREEN`, `RED`, `YELLOW`, `UNKNOWN`
    </ResponseField>

    <ResponseField name="new_quality_score" type="enum<string>">
      Available options: `GREEN`, `RED`, `YELLOW`, `UNKNOWN`
    </ResponseField>
  </Expandable>
</ResponseField>

### Message Template Status Update

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="event" type="enum<string>">
      Available options: `APPROVED`, `ARCHIVED`, `DELETED`, `DISABLED`, `FLAGGED`, `IN_APPEAL`, `LIMIT_EXCEEDED`, `LOCKED`, `PAUSED`, `PENDING`, `REINSTATED`, `PENDING_DELETION`, `REJECTED`
    </ResponseField>

    <ResponseField name="reason" type="string | null" />

    <ResponseField name="other_info" type="object">
      <Expandable>
        <ResponseField name="title" type="enum<string>">
          Available options: `FIRST_PAUSE`, `SECOND_PAUSE`, `RATE_LIMITING_PAUSE`, `UNPAUSE`, `DISABLED`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Message Echo Received

<ResponseField name="payload" type="object">
  This Trigger has no payload.
</ResponseField>

### Reaction Added

### Reaction Removed

### Template Category Update

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Not receiving messages from bot on WhatsApp">
    Until Meta has verified your business, your bot won't be able to send messages to WhatsApp users, even if you've configured it correctly.

    If you need to test out your bot right away, you can use the [WhatsApp Playground](#playground) while waiting for business verification.
  </Accordion>

  <Accordion title="Meta business verification taking too long">
    Unfortunately, we can't help speed up Meta's business verification process.

    If you need to test out your bot right away, you can use the [WhatsApp Playground](#playground) while waiting for business verification.
  </Accordion>

  <Accordion title="Bot receiving WhatsApp messages, but not sending messages back">
    There may be a problem with the payment method in your WhatsApp business account. Check the billing hub and make sure your [payment method](https://business.facebook.com/billing_hub/) is configured correctly.
  </Accordion>
</AccordionGroup>


# Mapping from Botpress to WhatsApp
Source: https://botpress.com/docs/integrations/integration-guides/whatsapp/mapping/botpress-to-whatsapp

Content mapping for the official WhatsApp integration.

## Overview

Here's a breakdown of how WhatsApp treats data it receives from Botpress:

| Botpress Type        | WhatsApp Type                                                                                                 |
| :------------------- | :------------------------------------------------------------------------------------------------------------ |
| `text`               | [Text Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#text-object)         |
| `text` with Markdown | [Text Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#text-object)         |
| `image`              | [Media Image Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object) |
| `audio`              | [Media Audio Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object) |
| `video`              | [Media Video Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object) |
| `file`               | [Media File Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object)  |
| `location`           | [Location Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#location-object) |

Some data types have restrictions in WhatsApp:

## Choices

[Choices](https://botpress.com/docs/capture-information) in Botpress are mapped to [Interactive Objects](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object) of the type `list` in WhatsApp.

WhatsApp renders choices differently depending on how many choices you specify in Botpress:

| Amount of Choices in Botpress |      How They're Rendered in WhatsApp      |
| :---------------------------: | :----------------------------------------: |
|              1-3              |                   Buttons                  |
|              4-10             |                  Dropdown                  |
|           11 or More          | Multiple dropdowns (up to 10 choices each) |

### Labels

In WhatsApp, choices require a label. Since Botpress Studio doesn't currently support labels for choice Cards, WhatsApp uses *“Choose…”* by default.

### Character Limit

In WhatsApp:

* Button titles are limited to 19 characters
* Dropdown choice titles are limited to 23 characters

If a title exceeds the limit, WhatsApp will automatically shorten it:

| Title in Botpress             | WhatsApp Button          | WhatsApp Dropdown            |
| :---------------------------- | :----------------------- | :--------------------------- |
| "This is a title in Botpress" | "This is a title in ..." | "This is a title in Botp..." |

***

## Cards

[Cards](https://botpress.com/docs/capture-information) in Botpress are mapped to [Interactive Objects](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object) of the type `list` in WhatsApp.

### Links

WhatsApp only supports one link (label and URL) on a Card. If your Botpress Card has multiple links, WhatsApp will split them into multiple empty Cards.

### Reply Button

WhatsApp only supports 3 "reply" action buttons on a Card. If your Botpress Card has more than three of these buttons, WhatsApp will split them into multiple Cards.

***

## Stickers

WhatsApp will treat an image as a [Sticker](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/sticker-messages) if it meets the following conditions:

* The image is in WebP format
* The image is **exactly** 512x512 in size
* The image is less than 512kb

If the image doesn't meet these conditions, the message won't be sent and a warning will be emitted.

***

## Files

When sending a file to WhatsApp, the file's name will be changed to whatever is specific in the **Title** field of the [Send Message Card](/docs/studio/concepts/cards/send-messages#file).

If you leave **Title** field blank, the file will be renamed with a generic name ("file") before being sent to WhatsApp. The WhatsApp message will still display the original file's name below the file itself.

<Note>
  You can also set a custom file name by sending the file using an [Execute Code Card](/docs/studio/concepts/cards/execute-code) and specifying a value for the `filename` attribute.
</Note>

***

## Carousels

WhatsApp doesn't natively support Carousels. If the bot sends a Carousel, WhatsApp will display each of its Cards in separate messages.


# Mapping from WhatsApp to Botpress
Source: https://botpress.com/docs/integrations/integration-guides/whatsapp/mapping/whatsapp-to-botpress

Content mapping for the official WhatsApp integration.

## Overview

In Botpress, you can read data sent from a user's WhatsApp message using the `event`'s properties. This is useful if you want to store user-provided data and access it later.

Here's a breakdown of how data from WhatsApp is mapped to Botpress:

| WhatsApp Message Type                                                                                                                                                                                                                          | Botpress Type | How to Read                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------- |
| [Text messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/text-messages)                                                                                                                                                | `text`        | `event.preview` or `event.payload` |
| Choices from interactive [buttons](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-reply-buttons-messages) or [lists](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-list-messages) | `text`        | `event.preview` or `event.payload` |
| [Image messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/image-messages)                                                                                                                                              | `image`       | `event.payload`                    |
| [Sticker messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/sticker-messages)                                                                                                                                          | `image`       | `event.payload`                    |
| [Audio messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/audio-messages)                                                                                                                                              | `audio`       | `event.payload`                    |
| [Video messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/video-messages)                                                                                                                                              | `video`       | `event.payload`                    |
| [Document messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/document-messages)                                                                                                                                        | `file`        | `event.payload`                    |
| [Location messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/location-messages)                                                                                                                                        | `location`    | `event.payload`                    |

## Read data from a payload

To read data from `event.payload`:

1. Add a **Wait for User Input** Card to the Node where you want to prompt the user.
2. After that Card, check that `event.type` is equal to the data type you're expecting from the user.
3. Read `event.payload`.

The payload's properties depend on the data type:

<AccordionGroup>
  <Accordion title="Text">
    <ResponseField name="text" type="string">
      The content of the message
    </ResponseField>

    <ResponseField name="value" type="string">
      The value of the last message. Only specified for choices, postbacks, and buttons
    </ResponseField>
  </Accordion>

  <Accordion title="Image">
    <ResponseField name="imageUrl" type="string">
      The URL of the image file
    </ResponseField>
  </Accordion>

  <Accordion title="Audio">
    <ResponseField name="audioUrl" type="string">
      The URL of the audio file
    </ResponseField>
  </Accordion>

  <Accordion title="Video">
    <ResponseField name="videoUrl" type="string">
      The URL of the video file
    </ResponseField>
  </Accordion>

  <Accordion title="File">
    <ResponseField name="fileUrl" type="string">
      The URL of the file
    </ResponseField>

    <ResponseField name="filename" type="string">
      The name of the file
    </ResponseField>
  </Accordion>

  <Accordion title="Location">
    <ResponseField name="latitude" type="number">
      The latitude coordinate of the location
    </ResponseField>

    <ResponseField name="longitude" type="number">
      The longitude coordinate of the location
    </ResponseField>

    <ResponseField name="title" type="string">
      The title of the location (Optional)
    </ResponseField>

    <ResponseField name="address" type="string">
      The address of the location (Optional)
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Get raw file contents

By default, any media sent by a user is automatically uploaded to the Botpress [Files API](/docs/api-reference/files-api/). This means you can read the raw file contents directly from the payload's URL.

For example, if you prompt the user to send an image, you can read `{{event.payload.imageUrl}}` to get the image.

<Tip>
  You can also set an expiry time for downloaded files—just update the **Downloaded Media Expiry** field in the **Configuration** menu.
</Tip>

### From WhatsApp API

If you'd rather get file contents from a WhatsApp media URL, you can disable **Download Media** in the **Configuration** menu. When disabled, you'll have to authenticate with the WhatsApp API to get files.

<Accordion title="Get raw file content from the WhatsApp API">
  <Steps>
    <Step title="Set a configuration variable">
      1. In your dashboard, navigate to your bot's **Configuration Variables** section in the left sidebar.
      2. Create a [Configuration Variable](https://botpress.com/docs/configuration-variables-1)  named `WHATSAPP_ACCESS_TOKEN`.
      3. Set its value to your WhatsApp access token.
    </Step>

    <Step title="Make a `GET` request">
      Now you can make an HTTP `GET` request to get the raw file data:

      ```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      const whatsappAccessToken = env.WHATSAPP_ACCESS_TOKEN

      const response = await axios.get(event.payload.<URL>, {
        headers: {
          Authorization: `Bearer ${whatsappAccessToken}`,
        },
      })
      ```

      Be sure to:

      * Replace `<URL>` with the actual URL provided in the payload
      * Pass `whatsappAccessToken` as a `Bearer` token in the HTTP `Authorization` header

        <Note>
          For more information, check the [WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media/#download-media) on downloading media files.
        </Note>
    </Step>
  </Steps>
</Accordion>

## Tags

You can read `event` tags to get information about the current WhatsApp user and conversation:

### Phone number

To get the user's phone number:

`event.tags.conversation['whatsapp:userPhone']`

This number contains the country code. It has no spaces, dashes (-) or symbols.

### Phone number ID

To get the conversation's WhatsApp phone number ID:

`event.tags.conversation['whatsapp:botPhoneNumberId']`

This is useful if you have multiple phone number IDs pointing to the same bot.

### Check if message is reply

To check if a message was a reply to another:

`event.tags.message['whatsapp:replyTo']`

If the message is a reply, the tag's value will be the Botpress `messageId` of the quoted message.


# Start a conversation on WhatsApp through a webhook
Source: https://botpress.com/docs/integrations/integration-guides/whatsapp/start-conversation-through-webhook

Trigger a new WhatsApp conversation from an external system using the Webhook integration and the Start Conversation Card.

## Prerequisites

<Info>
  You will need:

  * A [configured WhatsApp integration](./introduction.mdx)
  * A [WhatsApp Message Template](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/) (required for starting conversations proactively)
</Info>

This guide walks you through starting a WhatsApp conversation when an external system sends a request to your bot's webhook. Use this when you want to initiate a chat from your backend, CRM, or another service (for example, when a support ticket is created or a user signs up).

## 1. Install and configure the Webhook integration

<Steps>
  <Step title="Install the Webhook integration">
    In Botpress Studio, select **Explore Hub** in the upper-right corner. Search for **Webhook**, then select **Install Integration**.
  </Step>

  <Step title="Copy your webhook URL">
    Open the integration's **Configuration** page. Copy the webhook URL shown there (it starts with `https://webhook.botpress.cloud/`).

    <img alt="Webhook Configuration page with webhook URL" />
  </Step>

  <Step title="Send requests to the webhook">
    From your external system, send a POST request to this URL with the payload you need (for example, the user's phone number and template variables). Ensure the request body is JSON and that you use the same URL when testing in Studio.
  </Step>
</Steps>

<Note>
  If you configured a **Secret** for the integration, include it in the request as the `x-bp-secret` header. For more details, see [Send data to your webhook](/docs/integrations/integration-guides/webhook#send-data-to-your-webhook).
</Note>

## 2. Add the webhook trigger and Start Conversation in Studio

<Steps>
  <Step title="Add the Event trigger">
    Open the [Workflow](/docs/studio/concepts/workflows) where you want to handle the webhook. Right-click on the canvas and select **Trigger**, then choose the **Event** trigger from the Webhook integration.

    <img alt="Add Event trigger from Webhook" />
  </Step>

  <Step title="Add the Start Conversation Card">
    Add a Node after the trigger and add the **Start Conversation** Card to it.

    <img alt="Add Start Conversation Card to node" />

    Configure the Card:

    * **User Phone**: Use the phone number from your webhook payload (for example, `event.payload.body.userPhone` if you send `{ "userPhone": "+1234567890" }`).
    * **Template Name** and **Template Language**: Your approved WhatsApp message template and its language.
    * **Template Variables JSON**: If your template has variables, pass them from the webhook payload (for example, `event.payload.body.templateVariables`).

      <img alt="Start Conversation Card with User Phone, Template name, Template language, and Template variables" />
  </Step>

  <Step title="Store the WhatsApp conversation ID">
    In the Start Conversation Card, set **Store result in** to a [Workflow variable](/docs/studio/concepts/variables/scopes/workflow) (for example, `whatsAppOutput`). This variable will hold the new conversation's ID.

    <img alt="Store output value in workflow variable" />
  </Step>
</Steps>

## 3. Set the conversation ID so the rest of the Workflow runs in the same conversation

So that subsequent nodes (such as the [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) or your main bot Workflow) run in the same WhatsApp conversation, set `event.conversationId` to the ID returned by the Start Conversation Card.

<Steps>
  <Step title="Add an Execute Code Card">
    Add an **Execute Code** Card in the same Node (after Start Conversation) or in a new Node connected right after it.

    <img alt="Add Execute Code Card" />
  </Step>

  <Step title="Set the conversation ID">
    In the Execute Code Card, assign the conversation ID from the Start Conversation output to the event:

    ```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    event.conversationId = workflow.whatsAppOutput.conversationId
    ```

    <img alt="Store result in workflow variable" />

    Replace `whatsAppOutput` with the name of the variable you chose in **Store result in** for the Start Conversation Card.
  </Step>
</Steps>

<Note>
  The Start Conversation Card returns an object with a `conversationId` property. By setting `event.conversationId`, you ensure that any subsequent nodes (including the [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) or your main Workflow) continue in the same WhatsApp conversation.
</Note>

## 4. Connect to your main bot Workflow

Connect the node that contains the rest of your main Workflow to your **START** node.

<img alt="Workflow with start connection to main Workflow" />

That way, when the webhook fires:

1. The Event trigger runs.
2. The Start Conversation Card starts a WhatsApp conversation and stores its ID.
3. The Execute Code Card sets `event.conversationId` to that WhatsApp conversation ID.
4. The conversation continues in your main Workflow (for example, in the [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) or your regular bot Workflow).

<Check>
  When your external system POSTs to the webhook URL with the right payload (user phone, template name, etc.), your bot will start a WhatsApp conversation and then follow your main Workflow for that conversation.
</Check>


# Start a WhatsApp conversation proactively
Source: https://botpress.com/docs/integrations/integration-guides/whatsapp/whatsapp-start-proactively

Proactively start a WhatsApp conversation with a specific user.

<Info>
  You will need:

  * A [configured WhatsApp integration](./introduction.mdx)
  * A [WhatsApp Message Template](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/)
</Info>

<Note>
  WhatsApp only allows proactively sending messages if they're created from a template. You can create a template from your [WhatsApp Manager dashboard](https://business.facebook.com/latest/whatsapp_manager/message_templates?business_id=3818287771769899\&tab=message-templates\&nav_ref=whatsapp_manager\&asset_id=1022022276691875).

  After WhatsApp reviews and approves your template, follow the steps in this guide.
</Note>

## Setup

<Steps>
  <Step title="Add the Start Conversation Card">
    In Studio, add a **Start Conversation** Card to any Node:

    <img alt="Start Conversation" />
  </Step>

  <Step title="Fill in the required fields">
    Fill in the fields:

    <AccordionGroup>
      <Accordion title="User Phone">
        The user's phone number, including the country code.

        **Example**: `+1 123 456 7890`
      </Accordion>

      <Accordion title="Template Name">
        The name of your WhatsApp message template.

        **Example**: `proactive_message`
      </Accordion>

      <Accordion title="Template Language (Optional)">
        The language code for your WhatsApp message template. Defaults to `en_US`.

        <Warning>
          Although this field is optional, an error will occur if you leave the field blank and your message template's language isn't **English (US)**.
        </Warning>

        <Tabs>
          <Tab title="Country qualifier">
            If the language you selected for your template has a country qualifier, then you need to specify a value in the `language_COUNTRY` format, where:

            * `language` is the 2-letter lowercase [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
            * `COUNTRY` is the 2-letter uppercase [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

            For example, if you selected the **English (UK)** option, enter `en_GB`.
          </Tab>

          <Tab title="No country qualifier">
            If the language you selected for your template has no country qualifier, just specify the 2-letter lowercase [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).

            For example, if you selected the **French** option, enter `fr`.
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="Template Variables JSON (Optional)">
        A JSON array containing the values for your message template's variables.

        WhatsApp uses numbers to name variables within message templates. For example, if you have two variables, you need to name them `{{1}}` and `{{2}}`

        When you enter your JSON array in Botpress, you can order the entries based on how you want WhatsApp to assign the values:

        ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        ["First value", "Second value"]
        ```

        With the above array:

        * `"First value"` will be assigned to `{{1}}`
        * `"Second value"` will be assigned to `{{2}}`.
      </Accordion>

      <Accordion title="Sender Phone Number ID (Optional)">
        The WhatsApp Phone Number ID that will message your user. Defaults to the Phone Number ID you used to configure your integration.

        <Note>
          To use a different WhatsApp Phone Number ID, you need to have added it via your [Meta developer dashboard](https://developers.facebook.com/apps/).
        </Note>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

<Check>
  Your bot is ready to proactively start a conversation with your user!
</Check>

## Access the Conversation ID

You can access the proactively started conversation's ID in Studio by storing the **Start Conversation** Card's output in a variable. Just select a variable to store the value in:

<img alt="Output Value field" />

The output value of this action will be an object with the following structure:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  conversationId: 'xxxxxxxxxxxxxxxxxxxxx'
}
```

## Create the conversation from code

You can also call `actions.whatsapp.startConversation` in an [Execute Code](/docs/studio/concepts/cards/execute-code) Card to start a conversation:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
actions.whatsapp.startConversation({
  conversation: {
    userPhone: '+1 123 456 7890',
    templateName: 'test_message',
    templateLanguage: 'en',
    templateVariablesJson: JSON.stringify(['First value', 'Second value'])
  }
})
```


# Workable
Source: https://botpress.com/docs/integrations/integration-guides/workable

Add a bot to Workable using the official integration.

<OpenInHub />

The official Workable integration allows your bot to create and manage your Workable candidates.

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Workable account](https://id.workable.com/oidc/i/BtMboWMgw2NuejkYxadf_)
</Info>

<Steps>
  <Step title="Install the integration in Botpress">
    First, install the integration to your bot:

    1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
    2. Search for the **Workable** integration, then select **Install Integration**.
    3. Fill in the **Account subdomain** field with your company's subdomain (`https://mycompany.workable.com`)
    4. Leave the **API access token** field empty for now—you'll come back to them after getting your Workable API key.
  </Step>

  <Step title="Get your Workable API key">
    Next, get your Workable API key:

    1. [Log in to your Workable dashboard](https://id.workable.com/oidc/i/BtMboWMgw2NuejkYxadf_).
    2. Select your profile picture and go to **Settings**.
    3. In the left navigation bar, go to **Integrations > Apps**.
    4. Scroll to **API Access Tokens**, then select **Generate API token**.
    5. Add the `r_candidates` and `w_candidates` scopes.
    6. Copy the generated token.
  </Step>

  <Step title="Configure the integration in Botpress">
    Now, you can finish setting up the integration in Botpress:

    1. In the integration's **API access token** field, paste your Workable API key.
    2. Select **Save Configuration**.
  </Step>
</Steps>

<Check>
  Your integration is ready. You can use the integration's [Cards](#cards) and [Triggers](#triggers) to interact with your Workable candidates.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Create candidate in job

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="enum<string>">
              Available options: `academiaedu`, `angellist`, `behance`, `bitbucket`, `blogger`, `crunchbase`, `dandyid`, `delicious`, `deviantart`, `digg`, `doyoubuzz`, `dribble`, `dribbble`, `econsultancy`, `facebook`, `flavorsme`, `flickr`, `fullcontact`, `getglue`, `gist`, `github`, `goodreads`, `googleplus`, `gravatar`, `hackernews`, `hiim`, `klout`, `lanyrd`, `linkedin`, `myspace`, `ohloh`, `orkut`, `pinterest`, `quora`, `reddit`, `scribd`, `slideshare`, `stackexchange`, `stackoverflow`, `tumblr`, `twitter`, `typepad`, `vk`, `wordpress`, `xing`
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="imageUrl" type="string | null" />

        <ResponseField name="disqualifiedAt" type="string | null" />

        <ResponseField name="outboundMailbox" type="string | null" />

        <ResponseField name="uploaderId" type="string | null" />

        <ResponseField name="coverLetter" type="string | null" />

        <ResponseField name="summary" type="string | null" />

        <ResponseField name="educationEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="degree" type="string | null" />

            <ResponseField name="fieldOfStudy" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="experienceEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="summary" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />

            <ResponseField name="company" type="string | null" />

            <ResponseField name="industry" type="string | null" />

            <ResponseField name="current" type="boolean | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="skills" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="answers" type="array">
          <Expandable title="array item properties">
            <ResponseField name="question" type="object">
              <Expandable>
                <ResponseField name="body" type="string | null" />
              </Expandable>
            </ResponseField>

            <ResponseField name="answer" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="resumeUrl" type="string | null" />

        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string | null" />

            <ResponseField name="username" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="location" type="object | null" />

        <ResponseField name="originatingCandidateId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Create candidate in talent pool

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="enum<string>">
              Available options: `academiaedu`, `angellist`, `behance`, `bitbucket`, `blogger`, `crunchbase`, `dandyid`, `delicious`, `deviantart`, `digg`, `doyoubuzz`, `dribble`, `dribbble`, `econsultancy`, `facebook`, `flavorsme`, `flickr`, `fullcontact`, `getglue`, `gist`, `github`, `goodreads`, `googleplus`, `gravatar`, `hackernews`, `hiim`, `klout`, `lanyrd`, `linkedin`, `myspace`, `ohloh`, `orkut`, `pinterest`, `quora`, `reddit`, `scribd`, `slideshare`, `stackexchange`, `stackoverflow`, `tumblr`, `twitter`, `typepad`, `vk`, `wordpress`, `xing`
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="imageUrl" type="string | null" />

        <ResponseField name="disqualifiedAt" type="string | null" />

        <ResponseField name="outboundMailbox" type="string | null" />

        <ResponseField name="uploaderId" type="string | null" />

        <ResponseField name="coverLetter" type="string | null" />

        <ResponseField name="summary" type="string | null" />

        <ResponseField name="educationEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="degree" type="string | null" />

            <ResponseField name="fieldOfStudy" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="experienceEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="summary" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />

            <ResponseField name="company" type="string | null" />

            <ResponseField name="industry" type="string | null" />

            <ResponseField name="current" type="boolean | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="skills" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="answers" type="array">
          <Expandable title="array item properties">
            <ResponseField name="question" type="object">
              <Expandable>
                <ResponseField name="body" type="string | null" />
              </Expandable>
            </ResponseField>

            <ResponseField name="answer" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="resumeUrl" type="string | null" />

        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string | null" />

            <ResponseField name="username" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="location" type="object | null" />

        <ResponseField name="originatingCandidateId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get candidate

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="imageUrl" type="string | null" />

        <ResponseField name="disqualifiedAt" type="string | null" />

        <ResponseField name="outboundMailbox" type="string | null" />

        <ResponseField name="uploaderId" type="string | null" />

        <ResponseField name="coverLetter" type="string | null" />

        <ResponseField name="summary" type="string | null" />

        <ResponseField name="educationEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="degree" type="string | null" />

            <ResponseField name="fieldOfStudy" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="experienceEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="summary" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />

            <ResponseField name="company" type="string | null" />

            <ResponseField name="industry" type="string | null" />

            <ResponseField name="current" type="boolean | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="skills" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="answers" type="array">
          <Expandable title="array item properties">
            <ResponseField name="question" type="object">
              <Expandable>
                <ResponseField name="body" type="string | null" />
              </Expandable>
            </ResponseField>

            <ResponseField name="answer" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="resumeUrl" type="string | null" />

        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string | null" />

            <ResponseField name="username" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="location" type="object | null" />

        <ResponseField name="originatingCandidateId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get job questions

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="questions" type="array">
      <Expandable title="array item properties">
        <ResponseField name="type" type="enum<string>">
          Available options: `free_text`, `multiple_choice`, `boolean`, `dropdown`, `numeric`, `date`, `file`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### List candidates

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="candidates" type="array">
      <Expandable title="array item properties">
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Update candidate

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="type" type="enum<string>">
              Available options: `academiaedu`, `angellist`, `behance`, `bitbucket`, `blogger`, `crunchbase`, `dandyid`, `delicious`, `deviantart`, `digg`, `doyoubuzz`, `dribble`, `dribbble`, `econsultancy`, `facebook`, `flavorsme`, `flickr`, `fullcontact`, `getglue`, `gist`, `github`, `goodreads`, `googleplus`, `gravatar`, `hackernews`, `hiim`, `klout`, `lanyrd`, `linkedin`, `myspace`, `ohloh`, `orkut`, `pinterest`, `quora`, `reddit`, `scribd`, `slideshare`, `stackexchange`, `stackoverflow`, `tumblr`, `twitter`, `typepad`, `vk`, `wordpress`, `xing`
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="textingConsent" type="enum<string>">
          Available options: `forced`, `declined`
        </ResponseField>

        <ResponseField name="imageSource" type="enum<string>">
          Available options: `academiaedu`, `angellist`, `behance`, `bitbucket`, `blogger`, `crunchbase`, `dandyid`, `delicious`, `deviantart`, `digg`, `doyoubuzz`, `dribble`, `dribbble`, `econsultancy`, `facebook`, `flavorsme`, `flickr`, `fullcontact`, `getglue`, `gist`, `github`, `goodreads`, `googleplus`, `gravatar`, `hackernews`, `hiim`, `klout`, `lanyrd`, `linkedin`, `myspace`, `ohloh`, `orkut`, `pinterest`, `quora`, `reddit`, `scribd`, `skype`, `slideshare`, `stackexchange`, `stackoverflow`, `tumblr`, `twitter`, `typepad`, `vk`, `wordpress`, `xing`
        </ResponseField>

        <ResponseField name="image" type="object">
          <Expandable>
            <ResponseField name="source" type="enum<string>">
              Available options: `academiaedu`, `angellist`, `behance`, `bitbucket`, `blogger`, `crunchbase`, `dandyid`, `delicious`, `deviantart`, `digg`, `doyoubuzz`, `dribble`, `dribbble`, `econsultancy`, `facebook`, `flavorsme`, `flickr`, `fullcontact`, `getglue`, `gist`, `github`, `goodreads`, `googleplus`, `gravatar`, `hackernews`, `hiim`, `klout`, `lanyrd`, `linkedin`, `myspace`, `ohloh`, `orkut`, `pinterest`, `quora`, `reddit`, `scribd`, `skype`, `slideshare`, `stackexchange`, `stackoverflow`, `tumblr`, `twitter`, `typepad`, `vk`, `wordpress`, `xing`
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="candidate" type="object">
      <Expandable>
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="imageUrl" type="string | null" />

        <ResponseField name="disqualifiedAt" type="string | null" />

        <ResponseField name="outboundMailbox" type="string | null" />

        <ResponseField name="uploaderId" type="string | null" />

        <ResponseField name="coverLetter" type="string | null" />

        <ResponseField name="summary" type="string | null" />

        <ResponseField name="educationEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="degree" type="string | null" />

            <ResponseField name="fieldOfStudy" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="experienceEntries" type="array">
          <Expandable title="array item properties">
            <ResponseField name="summary" type="string | null" />

            <ResponseField name="startDate" type="string | null" />

            <ResponseField name="endDate" type="string | null" />

            <ResponseField name="company" type="string | null" />

            <ResponseField name="industry" type="string | null" />

            <ResponseField name="current" type="boolean | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="skills" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="answers" type="array">
          <Expandable title="array item properties">
            <ResponseField name="question" type="object">
              <Expandable>
                <ResponseField name="body" type="string | null" />
              </Expandable>
            </ResponseField>

            <ResponseField name="answer" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="resumeUrl" type="string | null" />

        <ResponseField name="socialProfiles" type="array">
          <Expandable title="array item properties">
            <ResponseField name="name" type="string | null" />

            <ResponseField name="username" type="string | null" />
          </Expandable>
        </ResponseField>

        <ResponseField name="location" type="object | null" />

        <ResponseField name="originatingCandidateId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Candidate Created

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Candidate Moved

<ResponseField name="payload" type="object">
  <Expandable>
    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="email" type="string | null" />

        <ResponseField name="headline" type="string | null" />

        <ResponseField name="account" type="object | null" />

        <ResponseField name="stage" type="string | null" />

        <ResponseField name="stageKind" type="string | null" />

        <ResponseField name="disqualificationReason" type="string | null" />

        <ResponseField name="profileUrl" type="string | null" />

        <ResponseField name="domain" type="string | null" />

        <ResponseField name="hiredAt" type="string | null" />

        <ResponseField name="address" type="string | null" />

        <ResponseField name="phone" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Zapier
Source: https://botpress.com/docs/integrations/integration-guides/zapier



<OpenInHub />

<Info>
  The Botpress app for Zapier is currently in BETA. In order to use Botpress in your Zaps please [click here to obtain access](https://zapier.com/developer/public-invite/179950/2d89a44be6d7ddcae4ae23df0be19b3c/) to the private beta in Zapier.
</Info>

<img />

## Prerequisites

* A [Zapier](https://zapier.com/) account
* BETA access to the Botpress app in Zapier [request here](https://zapier.com/developer/public-invite/179950/2d89a44be6d7ddcae4ae23df0be19b3c/)
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/docs/get-started/quick-start)

## Setting up the Zapier integration in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Zapier integration then click on the "Install to Bot" button, now go back to your bot.

## Setting up a Zapier workflow

1. Create a new zap in your Zapier account and search for "Botpress" either in the Trigger or Action of your zap.
2. Zapier will guide you through the process of authenticating to your Botpress account, follow the steps provided there.
3. Once you have authenticated, when setting up the Trigger or Action of your zap to use Botpress you'll be asked for the "Webhook URL", which you can find in your Botpress Cloud dashboard inside the "Integrations" tab of your bot and then clicking on the Zapier integration.

### Using Botpress to trigger a Zapier workflow

1. If you're setting up Botpress as a Trigger in Zapier there will be an option to test the trigger and see some sample data that could be received from your bot. Use this to create the rest of your Zap.
2. To make your bot send real data to Zapier, you'll find a "Send to Zapier" action card in Botpress Studio which you can use to send data from your bot to your Zap:

<img />

3. It's recommended that you send your data in JSON format so you can send multiple value at once, as Zapier will automatically parse it. For example, you could use the following expression to send a JSON object with multiple values in the "Trigger Data" field of the "Send to Zapier" action:

```
{{ JSON.stringify({ myVariable1: workflow.myVariable1, myVariable2: workflow.myVariable2 }) }}
```

### Using Zapier to trigger an action in your Botpress bot

1. If you're setting it up as an Action in Zapier, you can send custom Event Data to your bot and an optional Correlation ID which you can use to associate individual zap runs with a particular event in your bot.

2. Zapier only allows entering a single text value for the Event Data, but you can put a Code Step from Zapier before the Botpress action in your zap in order to construct an object with multiple values and then use `JSON.stringify()` in your Code Step to convert the object to a text field that you can use in the last part of your zap as the Event Data to send to Botpress.

3. To receive data from Zapier in your bot, you can use the "Event from Zapier" trigger in the Studio:

<img />

4. Then add an Execute Code card with the following code assuming you sent your data in JSON format:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
workflow.zapierData = JSON.parse(event.payload.body)
```

5. Now the rest of your trigger workflow can use the `{{ workflow.zapierData }}` variable to access the data you sent from Zapier.

### Testing your Zapier integration

You can create an "echo" zap in Zapier to test if everything works well. For example, you can create a zap that triggers when you send a message to your bot and then sends the same message back to your bot.\
Here's what a simple echo zap would look like:

<img />

The first action receives an event from the bot, and the second one sends the same event back to the bot. You can see the events you receive on the "Discover Events" button on the node containing "Events from Zapier" card.

<img />

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Send to Zapier

<ResponseField name="output" type="object">
  This Card has no output.
</ResponseField>

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Event from Zapier


# Zendesk
Source: https://botpress.com/docs/integrations/integration-guides/zendesk

Integrate your bot with Zendesk using the official integration.

<OpenInHub />

The official Zendesk integration allows you to create and manage support tickets directly from your bot. You can also assign a Zendesk agent to communicate directly with the user, all within the same conversation initially handled by the bot.

<Warning>
  Zendesk integration versions below v3.0.0 are **deprecated** and will be retired on January 12, 2026.

  To avoid disruptions, upgrade to v3.0.0+ and reconnect using OAuth. If you’re already on v3.0.0+, no further action is required.
</Warning>

## Setup

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Zendesk account](https://www.zendesk.com/lp/brand/?utm_source=google\&utm_medium=Search-Paid\&utm_network=g\&utm_campaign=SE_AW_AM_CA_EN_N_Sup_Brand_TM_Alpha_D_H\&matchtype=e\&utm_term=zendesk\&utm_content=598844228779\&theme=\&gad_source=1\&gad_campaignid=7993749347\&gbraid=0AAAAADn4z6gHcJduDz_4dLVEw2Vc9I-lF\&gclid=Cj0KCQjwrPHABhCIARIsAFW2XBOh1fGjHUcrDUDTaKTms6Qyrpi6Vo80Jj9_StfCFnEjiR_REi9zoZEaAjFjEALw_wcB)
</Info>

<Note>
  We recommend that you **only link your Zendesk account with one bot**. Linking the same Zendesk account with multiple bots will raise an error and cause unexpected behaviour.
</Note>

<Steps>
  <Step>
    In Botpress Studio, select **Explore Hub** in the upper-right corner.
  </Step>

  <Step>
    Search for the **Zendesk** integration, then select **Install Integration**.
  </Step>

  <Step>
    In the **Configuration** menu, select **Authorize Zendesk**.
  </Step>

  <Step>
    Follow the instructions to connect Botpress to your Zendesk account.
  </Step>
</Steps>

<Check>
  Done! You can now create and manage support tickets directly from your bot.
</Check>

***

## Cards

Here's a reference for all [Cards](/docs/studio/concepts/cards/introduction) available with the integration:

### Call API

<ResponseField name="input" type="object">
  <Expandable>
    <ResponseField name="method" type="enum<string>">
      Available options: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
    </ResponseField>
  </Expandable>
</ResponseField>

### Close ticket

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="ticket" type="object">
      <Expandable>
        <ResponseField name="status" type="enum<string>">
          Available options: `new`, `open`, `pending`, `hold`, `solved`, `closed`
        </ResponseField>

        <ResponseField name="priority" type="string | null" />

        <ResponseField name="ticketFormId" type="string | null" />

        <ResponseField name="assigneeId" type="number | null" />

        <ResponseField name="externalId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Create Ticket

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="ticket" type="object">
      <Expandable>
        <ResponseField name="status" type="enum<string>">
          Available options: `new`, `open`, `pending`, `hold`, `solved`, `closed`
        </ResponseField>

        <ResponseField name="priority" type="string | null" />

        <ResponseField name="ticketFormId" type="string | null" />

        <ResponseField name="assigneeId" type="number | null" />

        <ResponseField name="externalId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Find Customer

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="customers" type="array">
      <Expandable title="array item properties">
        <ResponseField name="phone" type="string | null" />

        <ResponseField name="photo" type="string | null" />

        <ResponseField name="remotePhotoUrl" type="string | null" />

        <ResponseField name="role" type="enum<string>">
          Available options: `end-user`, `agent`, `admin`
        </ResponseField>

        <ResponseField name="externalId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Get ticket

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="ticket" type="object">
      <Expandable>
        <ResponseField name="status" type="enum<string>">
          Available options: `new`, `open`, `pending`, `hold`, `solved`, `closed`
        </ResponseField>

        <ResponseField name="priority" type="string | null" />

        <ResponseField name="ticketFormId" type="string | null" />

        <ResponseField name="assigneeId" type="number | null" />

        <ResponseField name="externalId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### List Agents

<ResponseField name="output" type="object">
  <Expandable>
    <ResponseField name="agents" type="array">
      <Expandable title="array item properties">
        <ResponseField name="phone" type="string | null" />

        <ResponseField name="photo" type="string | null" />

        <ResponseField name="remotePhotoUrl" type="string | null" />

        <ResponseField name="role" type="enum<string>">
          Available options: `end-user`, `agent`, `admin`
        </ResponseField>

        <ResponseField name="externalId" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Sync Knowledge Base

***

## Triggers

Here's a reference for all [Triggers](/docs/studio/concepts/triggers/) available with the integration:

<Tip>
  You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.
</Tip>

### Article Published

### Article Unpublished


# Bots-as-code
Source: https://botpress.com/docs/integrations/sdk/bots-as-code



Just like [Botpress Studio](/docs/studio/introduction), the Botpress SDK allows you to create bots. However, instead of using a web interface, you can use code to define your bots. These are called **bots-as-code**.

Bots-as-code are still visible in the [Dashboard](/docs/get-started/configure-your-workspace#manage-your-agents) and can be managed from there, but can't be edited using the Studio. Opening a bot-as-code in the Studio will display an empty bot.

## 1. Install The Botpress CLI

To get started, first install the Botpress CLI globally on your machine. You can do this by running the following command in your terminal:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install -g @botpress/cli
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install -g @botpress/cli
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add -g @botpress/cli
  ```
</CodeGroup>

<Note>All the following examples use `npm`, but feel free to use the package manager of your choice like `yarn` or `pnpm`.</Note>

You can check that your installation was successful by running the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp --help
```

## 2. Log in to Botpress

Next, log in to your Botpress account using the Botpress CLI. You can do this by running the following command in your terminal:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp login
```

This command will prompt you for a personal access token. You can create a new token by going to [the Dashboard](https://app.botpress.cloud) and navigating to the **Personal Access Tokens** page.

## 3. Initialize a New Bot

Next, create a new bot using the Botpress CLI. This will set up a new directory with the necessary files and structure for your bot.

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp init --type "bot" --name "my-bot" --template "empty"
```

## 4. Install Dependencies and Build

Once the bot is initialized, navigate to the bot directory and install the dependencies:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cd ./my-bot
npm i
bp build
```

## 5. Browse the Bot Files

You can now open the bot in VS Code or another code editor of your choice:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
code .
```

Here's a brief overview of the files and folders you'll find in the bot directory:

* `bot.definition.ts`: Contains the bot definition. It exports a data structure that describes your bot—what it can do, and how it can be used. This includes the bot's actions, events. The definition also allows declaring your bot integration dependencies. Keep reading this documentation to learn about all the concepts you can define in this file.

* `src/index.ts`: Contains the bot implementation. It exports a data structure that implements what was defined in the bot definition. Keep reading this documentation to learn about the available callbacks and handlers you can implement.

* `.botpress/`: Contains the bot output, generated by the build command. It includes types to help you implement your bot, and bundled JavaScript used to execute it. You can explore its contents, but avoid importing from nested files or folders, as its structure may change. Everything meant to be imported is available from the root of this folder.

* `package.json`, `tsconfig.json`: As with any Node.js TypeScript project, these files contain your package's metadata and dependencies, and the TypeScript configuration. The `tsconfig.json` file is pre-configured to offer the best experience with the Botpress SDK. Run `npm run check:type` to check for typing errors.

## 6. Install the Chat Integration

The Chat integration allows you to chat with your bot using HTTP requests. See the [Chat Integration](/docs/api-reference/chat-api/introduction) page for more information.

To install in your bot-as-code, run the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp add chat@latest
```

Then navigate to the `bot.definition.ts` file and add the following code:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { BotDefinition } from "@botpress/sdk";
import chat from "./bp_modules/chat";

export default new BotDefinition({}).addIntegration(chat, {
  enabled: true,
  configuration: {},
});
```

To refresh types available in your bot implementation, run the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp gen
```

## 7. Implement a message handlers

Let's add some content to the bot. Open the `src/index.ts` file and add the following code:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bot.on.message("*", async (props) => {
  const {
    conversation: { id: conversationId },
    ctx: { botId: userId },
  } = props;

  if (props.message.type !== "text") {
    await props.client.createMessage({
      conversationId,
      userId,
      tags: {},
      type: "text",
      payload: {
        text: "Sorry, I can only respond to text messages.",
      },
    });
    return;
  }

  await props.client.createMessage({
    conversationId,
    userId,
    tags: {},
    type: "text",
    payload: {
      text: `You said: ${props.message.payload.text}`,
    },
  });
});
```

This bot will respond to any message sent to it. It will echo back the text message sent by the user. If the user sends a non-text message, like an image, the bot will respond with a message saying it can only respond to text messages.

## 8. Deploy the Bot

Once you've made the necessary changes to your bot, you can deploy it to Botpress Cloud. Run the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp deploy --create-new-bot
```

You'll be prompted for some information and confirmations. The `--create-new-bot` flag will create a new bot in your workspace. If you want to deploy to an existing bot, you can omit this flag. The CLI will prompt you for the bot in which you want to deploy.

After deploying, go to [the Dashboard](https://app.botpress.cloud). You should see your bot listed there.

## 9. Chat with your bot

Now you can chat with your bot using the CLI. Run the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp chat
```

This command will prompt you for the bot you want to chat with. Select the bot you just deployed, and start chatting with it. Press the escape key to exit the chat.


# CLI reference
Source: https://botpress.com/docs/integrations/sdk/cli-reference

All commands and flags available with the Botpress CLI.

## Global flags

These flags are available for all commands:

| Flag              | Alias | Description                                         |
| ----------------- | ----- | --------------------------------------------------- |
| `--verbose`       | `-v`  | Enable verbose logging                              |
| `--confirm`       | `-y`  | Confirm all prompts                                 |
| `--json`          |       | Output raw JSON to stdout (useful for piping)       |
| `--botpress-home` |       | Path to Botpress home directory                     |
| `--profile`       | `-p`  | CLI profile from \$BP\_BOTPRESS\_HOME/profiles.json |

## Commands

### `login`

Login to Botpress Cloud.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp login
bp login --token your-token --workspace-id your-workspace-id
```

**Flags:**

| Flag             | Description           | Default                                                  |
| ---------------- | --------------------- | -------------------------------------------------------- |
| `--token`        | Personal Access Token |                                                          |
| `--workspace-id` | Workspace ID          |                                                          |
| `--api-url`      | Botpress server URL   | [https://api.botpress.cloud](https://api.botpress.cloud) |

***

### `logout`

Logout of Botpress Cloud.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp logout
```

***

### `init`

Initialize a new project.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp init
bp init --type bot --name my-bot
bp init --type integration --template webhook-message
```

**Flags:**

| Flag         | Description                                     | Default           |
| ------------ | ----------------------------------------------- | ----------------- |
| `--work-dir` | Path to the project                             | current directory |
| `--type`     | Project type: `bot`, `integration`, or `plugin` |                   |
| `--template` | Template to use                                 |                   |
| `--name`     | Name of the project                             |                   |

***

### `generate`

Generate typings for intellisense. Alias: `gen`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp generate
bp gen --work-dir ./my-project
```

**Flags:**

| Flag         | Description         | Default           |
| ------------ | ------------------- | ----------------- |
| `--work-dir` | Path to the project | current directory |

***

### `build`

Generate typings and bundle a project.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp build
bp build --work-dir ./my-project --minify false
```

**Flags:**

| Flag           | Description             | Default           |
| -------------- | ----------------------- | ----------------- |
| `--work-dir`   | Path to the project     | current directory |
| `--source-map` | Generate sourcemaps     | false             |
| `--minify`     | Minify the bundled code | true              |

***

### `bundle`

Bundle a Botpress project.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp bundle
bp bundle --work-dir ./my-project --source-map
```

**Flags:**

| Flag           | Description             | Default           |
| -------------- | ----------------------- | ----------------- |
| `--work-dir`   | Path to the project     | current directory |
| `--source-map` | Generate sourcemaps     | false             |
| `--minify`     | Minify the bundled code | true              |

***

### `serve`

Serve your project locally.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp serve
bp serve --port 8080 --secrets SECRET1=value1 SECRET2=value2
```

**Flags:**

| Flag         | Description                                    | Default           |
| ------------ | ---------------------------------------------- | ----------------- |
| `--work-dir` | Path to the project                            | current directory |
| `--port`     | Port to use                                    |                   |
| `--secrets`  | Values for bot and integration secrets (array) |                   |

***

### `dev`

Run your project in dev mode.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp dev
bp dev --port 3000 --secrets API_KEY=secret123
```

**Flags:**

| Flag             | Description                                    | Default           |
| ---------------- | ---------------------------------------------- | ----------------- |
| `--work-dir`     | Path to the project                            | current directory |
| `--api-url`      | Botpress server URL                            |                   |
| `--workspace-id` | Workspace ID                                   |                   |
| `--token`        | Personal Access Token                          |                   |
| `--secrets`      | Values for bot and integration secrets (array) |                   |
| `--source-map`   | Generate sourcemaps                            | false             |
| `--minify`       | Minify the bundled code                        | true              |
| `--port`         | Port to use                                    |                   |
| `--tunnel-url`   | Tunnel HTTP URL to use                         |                   |

***

### `deploy`

Deploy your project to the cloud.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp deploy
bp deploy --bot-id my-bot-id --visibility public
bp deploy --create-new-bot --no-build
```

**Flags:**

| Flag                 | Description                                            | Default           |
| -------------------- | ------------------------------------------------------ | ----------------- |
| `--work-dir`         | Path to the project                                    | current directory |
| `--api-url`          | Botpress server URL                                    |                   |
| `--workspace-id`     | Workspace ID                                           |                   |
| `--token`            | Personal Access Token                                  |                   |
| `--secrets`          | Values for bot and integration secrets (array)         |                   |
| `--bot-id`           | Bot ID to deploy (only for bots)                       |                   |
| `--no-build`         | Skip the build step                                    | false             |
| `--dry-run`          | Ask API not to perform actual operation                | false             |
| `--create-new-bot`   | Create new bot when deploying (only for bots)          | false             |
| `--source-map`       | Generate sourcemaps                                    | false             |
| `--minify`           | Minify the bundled code                                | true              |
| `--visibility`       | Project visibility: `public`, `private`, or `unlisted` | private           |
| `--allow-deprecated` | Allow deprecated features                              | false             |

***

### `add`

Install a package (integration or interface).

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp add teams@0.2.0
bp add llm --package-type interface
bp add knowledge --use-dev
```

**Arguments:**

| Argument     | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| `packageRef` | Package ID or name with optional version (e.g., teams\@0.2.0) |

**Flags:**

| Flag             | Description                                           | Default |
| ---------------- | ----------------------------------------------------- | ------- |
| `--api-url`      | Botpress server URL                                   |         |
| `--workspace-id` | Workspace ID                                          |         |
| `--token`        | Personal Access Token                                 |         |
| `--package-type` | Package type: `integration`, `interface`, or `plugin` |         |
| `--install-path` | Path where to install the package                     |         |
| `--use-dev`      | Use dev version if found                              | false   |

***

### `read`

Read and parse an integration definition.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp read
bp read --work-dir ./my-integration
```

**Flags:**

| Flag         | Description         | Default           |
| ------------ | ------------------- | ----------------- |
| `--work-dir` | Path to the project | current directory |

***

### `lint`

Lint an integration definition (experimental).

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp lint
bp lint --work-dir ./my-integration
```

**Flags:**

| Flag         | Description         | Default           |
| ------------ | ------------------- | ----------------- |
| `--work-dir` | Path to the project | current directory |

***

### `chat`

Chat with a bot directly from CLI (experimental).

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp chat my-bot-id
bp chat my-bot-id --chat-api-url https://chat.example.com
```

**Arguments:**

| Argument | Description         |
| -------- | ------------------- |
| `botId`  | Bot ID to chat with |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |
| `--chat-api-url` | Chat server URL       |         |

***

### `bots`

Bot related commands.

#### `create`

Create a new bot. Alias: `new`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp bots create --name my-bot
bp bots new --name my-bot --if-not-exists
```

**Flags:**

| Flag              | Description                                | Default |
| ----------------- | ------------------------------------------ | ------- |
| `--api-url`       | Botpress server URL                        |         |
| `--workspace-id`  | Workspace ID                               |         |
| `--token`         | Personal Access Token                      |         |
| `--name`          | Name of the bot to create                  |         |
| `--if-not-exists` | Do not create if bot with same name exists | false   |

***

#### `list`

List bots. Alias: `ls`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp bots list
bp bots ls --dev
```

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |
| `--dev`          | List only dev bots    | false   |

***

#### `get`

Get bot details.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp bots get my-bot-id
```

**Arguments:**

| Argument | Description       |
| -------- | ----------------- |
| `botRef` | Bot ID (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

#### `delete`

Delete a bot. Alias: `rm`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp bots delete my-bot-id
bp bots rm my-bot-id
```

**Arguments:**

| Argument | Description       |
| -------- | ----------------- |
| `botRef` | Bot ID (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

### `integrations`

Integration related commands.

#### `list`

List integrations. Alias: `ls`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp integrations list
bp integrations ls --name teams --dev
```

**Flags:**

| Flag               | Description                | Default |
| ------------------ | -------------------------- | ------- |
| `--api-url`        | Botpress server URL        |         |
| `--workspace-id`   | Workspace ID               |         |
| `--token`          | Personal Access Token      |         |
| `--name`           | Name filter                |         |
| `--version-number` | Version filter             |         |
| `--dev`            | List only dev integrations | false   |

***

#### `get`

Get integration details.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp integrations get teams@0.2.0
bp integrations get my-integration-id
```

**Arguments:**

| Argument         | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `integrationRef` | Integration ID or name with optional version (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

#### `delete`

Delete an integration. Alias: `rm`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp integrations delete teams@0.2.0
bp integrations rm my-integration-id
```

**Arguments:**

| Argument         | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `integrationRef` | Integration ID or name with optional version (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

### `interfaces`

Interface related commands.

#### `list`

List interfaces. Alias: `ls`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp interfaces list
bp interfaces ls
```

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

#### `get`

Get interface details.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp interfaces get llm@5.1.0
bp interfaces get my-interface-id
```

**Arguments:**

| Argument       | Description                                  |
| -------------- | -------------------------------------------- |
| `interfaceRef` | Interface ID or name with version (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

#### `delete`

Delete an interface. Alias: `rm`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp interfaces delete llm@5.1.0
bp interfaces rm my-interface-id
```

**Arguments:**

| Argument       | Description                                  |
| -------------- | -------------------------------------------- |
| `interfaceRef` | Interface ID or name with version (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

### `plugins`

Plugin related commands.

#### `list`

List plugins. Alias: `ls`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp plugins list
bp plugins ls --name knowledge
```

**Flags:**

| Flag               | Description           | Default |
| ------------------ | --------------------- | ------- |
| `--api-url`        | Botpress server URL   |         |
| `--workspace-id`   | Workspace ID          |         |
| `--token`          | Personal Access Token |         |
| `--name`           | Name filter           |         |
| `--version-number` | Version filter        |         |

***

#### `get`

Get plugin details.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp plugins get knowledge@0.0.1
bp plugins get my-plugin-id
```

**Arguments:**

| Argument    | Description                               |
| ----------- | ----------------------------------------- |
| `pluginRef` | Plugin ID or name with version (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

#### `delete`

Delete a plugin. Alias: `rm`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp plugins delete knowledge@0.0.1
bp plugins rm my-plugin-id
```

**Arguments:**

| Argument    | Description                               |
| ----------- | ----------------------------------------- |
| `pluginRef` | Plugin ID or name with version (required) |

**Flags:**

| Flag             | Description           | Default |
| ---------------- | --------------------- | ------- |
| `--api-url`      | Botpress server URL   |         |
| `--workspace-id` | Workspace ID          |         |
| `--token`        | Personal Access Token |         |

***

### `profiles`

CLI profile management commands.

#### `list`

List all available profiles. Alias: `ls`

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp profiles list
bp profiles ls
```

***

#### `active`

Get the profile properties you are currently using.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp profiles active
```

***

#### `use`

Set the current profile.

**Usage:**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp profiles use my-profile
bp profiles use production
```

**Arguments:**

| Argument       | Description                                          |
| -------------- | ---------------------------------------------------- |
| `profileToUse` | Profile name from \$BP\_BOTPRESS\_HOME/profiles.json |


# Installation
Source: https://botpress.com/docs/integrations/sdk/installation



To get started, install the Botpress CLI globally on your machine. The CLI includes the Botpress SDK and other useful packages for developing with Botpress.

Run the following command in your terminal:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install -g @botpress/cli
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install -g @botpress/cli
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add -g @botpress/cli
  ```
</CodeGroup>

<Note>All the examples in this section use `npm`, but feel free to use the package manager of your choice like `yarn` or `pnpm`.</Note>

You can check that your installation was successful by running the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp --help
```


# Integrations Concepts
Source: https://botpress.com/docs/integrations/sdk/integration/concepts



This guide is a breakdown of the concepts introduced in the [Get Started](./getting-started) and [Messaging](./messaging) guides. The goal is to provide a deeper understanding of the concepts and components that make up integrations in Botpress.

<Note>Most concepts listed below can define data schemas. For this the SDK uses [Zod](https://zod.dev), a TypeScript-first schema validation library. These schemas allow for better IntelliSense for integration developers, autogenerated forms for bot developers in the Studio and validation of data at runtime</Note>

## Configuration

Integrations can define a configuration schema. This dictates the structure of data that bot developers must provide when installing the integration. This schema is used to display the form bot developers see when installing the integration in the Studio. For example, you can define a schema that:

* Requires users to supply their own API key (or other secrets)
* Provides additional configuration options for the integration

<Accordion title="Example: Linear">
  Here's how the official [Linear](https://botpress.com/integrations/linear) integration [defines its configuration schema](https://github.com/botpress/botpress/blob/840e7e65901d0234353ad6890b0ad49a734b4de5/integrations/linear/definitions/index.ts#L19-L32):

  ```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  export const configurations = {
    apiKey: {
      title: 'API Key',
      description: 'Configure Linear with an API Key.',
      schema: z.object({
        apiKey: z.string().title('API Key').describe('The API key for Linear'),
        webhookSigningSecret: z
          .string()
          .secret()
          .title('Webhook Signing Secret')
          .describe('The secret key for verifying incoming Linear webhook events'),
      }),
    },
  } as const satisfies IntegrationDefinitionProps['configurations']
  ```

  And how the configuration schema is rendered in Botpress Studio:

  <Frame>
    <img alt="Configuration schema" />

    <img alt="Configuration schema" />
  </Frame>
</Accordion>

### Provide multiple schemas

Integrations can also provide multiple configuration schemas to support different use cases or environments. This allows bot developers to select the appropriate configuration method based on their needs.

<Accordion title="Example: GitHub">
  For example, here's how the official [GitHub](https://botpress.com/integrations/github) integration [defines its configuration schemas](https://github.com/botpress/botpress/blob/840e7e65901d0234353ad6890b0ad49a734b4de5/integrations/github/src/definitions/index.ts#L28-L65):

  ```ts expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  export const configurations = {
    manualApp: {
      title: 'Manual configuration',
      description: 'Configure manually with your own GitHub App',
      schema: z.object({
        githubAppId: z
          .string()
          .min(1)
          .title('GitHub App ID')
          .describe('Can be found in the GitHub App settings. OAuth apps are not supported.'),
        githubAppPrivateKey: multiLineString
          .min(1)
          .secret()
          .title('GitHub App Private Key')
          .describe('The raw contents of the RSA private key. Can be downloaded from the GitHub App settings.')
          .placeholder('-----BEGIN RSA PRIVATE KEY-----\n\n...\n\n-----END RSA PRIVATE KEY-----'),
        githubAppInstallationId: z
          .number()
          .positive()
          .title('GitHub App Installation ID')
          .describe('Please refer to the integration documentation for details on how to obtain this.'),
        ...webhookSecret,
      }),
    },
    manualPAT: {
      title: 'Manual configuration',
      description: 'Configure manually with a Personal Access Token',
      schema: z.object({
        personalAccessToken: z
          .string()
          .min(1)
          .secret()
          .title('Personal Access Token')
          .describe('An organization-level GitHub Personal Access Token with the necessary permissions.'),
        ...webhookSecret,
      }),
    },
  } as const satisfies sdk.IntegrationDefinitionProps['configurations']
  ```

  And how they're rendered in Botpress Studio:

  <Tabs>
    <Tab title="First schema">
      <Frame>
        <img alt="First schema" />

        <img alt="First schema" />
      </Frame>
    </Tab>

    <Tab title="Second schema">
      <Frame>
        <img alt="Second schema" />

        <img alt="Second schema" />
      </Frame>
    </Tab>
  </Tabs>
</Accordion>

## Events

Integrations define events that represent activities within the external service. For example:

* A Slack integration might define a `memberLeftChannel` event
* A GitHub integration might define a `pullRequestOpened` event
* A Dropbox integration might define a `fileUploaded` event

Events are defined with a schema that specifies the data structure of the event payload. Bots can subscribe to these events to trigger specific handlers or Workflows.

## Actions

Integrations expose actions that bots can invoke to interact with the external service. For example:

* Retrieving or updating information in external systems
* Performing operations on behalf of users

Actions are defined with an input and output schema, which specifies the expected data structure for both the input parameters and the response. These actions are made available to bots in the Studio with action cards.

## Channels

Integrations can define communication channels that represent different communication mediums within the integrated platform. For example:

* Different channels might represent group chats, direct messages, or threads
* Each channel specifies the types of messages it can send and receive
* Channel definitions handle platform-specific message formatting and delivery

For example, a GitHub integration might define a `pullRequest` channel and an `issue` channel, each with its own message format and delivery method.

## States

Integrations can define states which are data structures attached to either a conversation, a user, or global to the whole bot. When defining a state, the integration must provide its schema, which describes the data structure of the state's payload.

## Tags

Integrations can define tags that allow bot developers to add metadata to conversations, individual messages, or users. Only tags defined in the integration definition can be used at runtime.

Just like states, tags can be used as a form of memory, enabling the integration to store and retrieve information. However, tags have key differences from states:

* Tags values must be strings of less than 500 characters. This is to ensure that tags are lightweight and easy to manage.
* Tags can be used as filters for many list and get-or-create operations like `listMessages` and `getOrCreateUser`.
* Tags are returned in the Botpress API with the entities they're attached to. If you get a message, user or conversation, you will also get the tags attached to it without having to do a separate API call.

## Secrets

Integrations can define secrets, such as API keys, tokens, or other sensitive values. While they're most often used for authentication with external services, they can represent any sensitive information required by the integration.

Secrets are defined in the integration definition. When deploying an integration, the CLI prompts for any secrets (and prevents deployment if a required secret is omitted). The secret values are then available at runtime for the integration developer to use.

Secrets are global to the integration and aren't scoped to individual bots.

## What's Next?

Now that you have a better understanding of these concepts, you should be able to build a nice and complete integration.

You can check the [Publish on Botpress Hub](./publish-your-integration-on-botpress-hub) page to learn how to publish your integration publicly and share it with the Botpress community.

You could also read the [Enable OAuth](./enable-oauth) page to learn how to allow users to install your integration with OAuth.


# Enable OAuth
Source: https://botpress.com/docs/integrations/sdk/integration/enable-oauth



Some Botpress-maintained integrations offer bot builders the choice between two different configuration methods:

* **Manual configuration**: Users bring their own app and manually provide Botpress with the required credentials
* **OAuth**: A one-click approach where users authorize the integration to access their information. This is the case for Slack, GitHub, Linear, Notion and many more.

This feature isn't limited to official Botpress integrations—you can also enable OAuth in your own integrations. This guide walks you through how to do that.

## Setup

<Steps>
  <Step title="Create an Application in the external service">
    On the platform you're integrating with, create an OAuth application. This step varies per platform (Slack, GitHub, etc.), so refer to their documentation.

    When asked for an OAuth redirect URI, use:

    ```
    https://webhook.botpress.cloud/oauth
    ```

    If asked for a webhook URI, use:

    ```
    https://webhook.botpress.cloud/integration/global/$YOUR_INTEGRATION_NAME
    ```
  </Step>

  <Step title="Add a link template script in your integration definition">
    In your integration definition, add a `configurations` type with a `linkTemplateScript` field. This field is a path to a `.vrl` script relative to your integration's directory. The script generates the OAuth URL that users will be redirected to when clicking the OAuth button in the integration UI.

    For Slack, the link looks something like this:

    ```vrl theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    https://slack.com/oauth/v2/authorize?client_id=12345.67890&state={{ webhookId }}&redirect_uri={{ webhookUrl }}/oauth
    ```

    <Note>
      [VRL - Vector Remap Language](https://vector.dev/docs/reference/vrl/) is a small domain specific language that Botpress uses to manipulate data. In this case, it allows you to dynamically generate the OAuth URL based on the integration's configuration and the webhook ID. Your VRL script is called with the following variables:

      ```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type ScriptInput = {
        webhookId: string,   /** The integration's webhook ID */
        webhookUrl: string,  /** Botpress's global webhook endpoint */
      }
      ```
    </Note>

    Your script should generate a URL similar to the one above, but adapted to the platform you're integrating with. The important parts are:

    * The `state` parameter **must** equal the webhook ID and cannot contain any other information. It's used by Botpress to identify which bot and which integration initiated the flow.
    * The `redirect_uri` **must** be:

      ```
      {{ webhookUrl }}/oauth
      ```

    When the OAuth flow completes, the platform will redirect to this URL, and Botpress will forward the request to your integration's webhook handler.
  </Step>

  <Step title="Handle the `/oauth` path in your integration">
    In your integration implementation, handle incoming requests with the `/oauth` path.

    Your code should:

    1. Extract the access token and any other relevant data from the request
    2. Store the token in an integration's [state](./concepts#states)
    3. Call [configureIntegration](../../../api-reference/runtime-api/openapi/configureIntegration) to associate the integration with a user or workspace ID from the third-party platform
  </Step>

  <Step title="Add an `identifier` with an `extractScript`">
    In your integration definition, add an `identifier` field with an `extractScript`:

    ```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    identifier: {
      extractScript: 'extract-id.vrl'
    }
    ```

    <Note>
      Just like the `linkTemplateScript`, this is a path to a `.vrl` script relative to your integration's directory. The script is executed when Botpress receives incoming requests on the global webhook. It should extract an external user or workspace ID from the request and return it in the format expected by Botpress. It's called with the following variables:

      ```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type ScriptInput = {
        path: string,                     /** The request path */
        method: string,                   /** The request HTTP method */
        query: string,                    /** The request query parameters */
        body?: string,                    /** The request body */
        headers: Record<string, string>,  /** The request headers */
        secrets: Record<string, string>,  /** The global secrets of your integration */
      }
      ```
    </Note>

    This script is used when receiving incoming requests on the global webhook. It should extract an external user or workspace ID from the request. Botpress uses this ID to route the request to the correct bot.
  </Step>
</Steps>

## Use global secrets

If your OAuth flow requires credentials like `client_id` or `client_secret`, you can provide them using global [secrets](./concepts#secrets). These can be accessed from your VRL scripts or code.

Once all of this is set up, users installing your integration will be able to authenticate with a single click—just like they can with Slack, GitHub, and other official integrations.

## What's Next?

If you feel like this page is missing some information, refer to the [Botpress GitHub repository](https://github.com/botpress/botpress) for examples of OAuth integrations. These examples showcase how OAuth can be implemented effectively and provide inspiration for your own integrations.

We left these integrations open-source for a reason! Feel free to explore the code, copy it, and adapt it to your own needs. If you find areas for improvement, you can contribute by opening an issue or a pull request.


# Get started
Source: https://botpress.com/docs/integrations/sdk/integration/getting-started

Build your first integration with Botpress.

<Note>
  If you're not a developer and just want to install an existing integration, check out the [integrations section](/docs/integrations/get-started/introduction).
</Note>

Integrations form the foundation of connectivity within the Botpress platform, enabling bots to interact with external services and systems. Through the Botpress SDK, developers can create custom integrations that connect bots to virtually any third-party service, from messaging platforms to data repositories and enterprise systems.

## 1. Install The Botpress CLI

To get started, first install the Botpress CLI globally on your machine. You can do this by running the following command in your terminal:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install -g @botpress/cli
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install -g @botpress/cli
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add -g @botpress/cli
  ```
</CodeGroup>

<Note>All the following examples use `npm`, but feel free to use the package manager of your choice like `yarn` or `pnpm`.</Note>

You can check that your installation was successful by running the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp --help
```

## 2. Log in to Botpress

Next, log in to your Botpress account using the Botpress CLI. You can do this by running the following command in your terminal:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp login
```

This command will prompt you for a personal access token. You can create a new token by going to [the Dashboard](https://app.botpress.cloud) and navigating to the **Personal Access Tokens** page.

## 3. Initialize a New Integration

Next, create a new integration using the Botpress CLI. This will set up a new directory with the necessary files and structure for your integration.

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp init --type "integration" --name "my-integration" --template "hello-world"
```

<Note>
  Choose a valid name for your integration by following these rules:

  * Use only lowercase letters
  * Include dashes ( **-** ) or underscores ( **\_** ) if desired
  * Avoid spaces and special characters like **!**, **@**, **#**, etc.

  If your integration name doesn't follow these rules, you'll get an error when you try to [deploy the integration](#7-deploy-the-integration).
</Note>

The CLI will prompt you for some information, including your Workspace or Workspace handle. If you don't have a Workspace handle yet, the CLI should claim one for you. You can also claim one manually by going to [the Dashboard](https://app.botpress.cloud) and navigating to the **Settings** page.

## 4. Install Dependencies and Build

Once the integration is initialized, navigate to the integration directory and install the dependencies:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cd ./my-integration
npm i
bp build
```

## 5. Browse the Integration Files

You can now open the integration in VS Code or another code editor of your choice:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
code .
```

Here's a brief overview of the files and folders you'll find in the integration directory:

* `integrations.definition.ts`: Contains the integration definition. It exports a data structure that describes your integration—what it is, what it can do, and how it can be used. This includes the integration's name, version, actions, events, channels, and other capabilities. The template you chose declares a single action, `helloWorld`, which accepts an optional `name` parameter and returns a greeting message. Keep reading this documentation to learn about all the concepts you can define in this file.

* `src/index.ts`: Contains the integration implementation. It exports a data structure that implements what was defined in the integration definition. Keep reading this documentation to learn about the available callbacks you can implement.

* `.botpress/`: Contains the integration output, generated by the build command. It includes types to help you implement your integration, and bundled JavaScript used to execute it. You can explore its contents, but avoid importing from nested files or folders, as its structure may change. Everything meant to be imported is available from the root of this folder.

* `icon.svg`, `hub.md`: These files contain the integration's icon and README. They're referenced in the integration definition.

* `package.json`, `tsconfig.json`: As with any Node.js TypeScript project, these files contain your package's metadata and dependencies, and the TypeScript configuration. The `tsconfig.json` file is pre-configured to offer the best experience with the Botpress SDK. Run `npm run check:type` to check for typing errors.

## 6. Update the Code to Remove Errors

The template you chose ships with unimplemented register callbacks. In `src/index.ts`, you'll see `register` and `unregister` functions with a body that looks like this:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
throw new sdk.RuntimeError('Invalid configuration')
```

Remove these error statements for now. You can come back later to implement your own validation logic.

## 7. Deploy the Integration

Once you've made the necessary changes to your integration, you can deploy it to Botpress Cloud. Run the following command:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
bp deploy
```

You'll be prompted for some information and confirmations. This integration will be deployed privately to your Workspace, and will only be visible and usable by members of your Workspace. As long as it remains private, you can update the same version by running the deploy command again. To deploy a new version, update the integration definition and run the deploy command once more.

After deploying, go to [the Dashboard](https://app.botpress.cloud) and navigate to the **Your Integrations** page. You should see your integration listed there.

## 8. Try Out Your Integration in Botpress Studio

Now you can test your integration:

1. Create a new bot or open an existing one in Botpress Studio.
2. Navigate to Botpress Hub and install your integration.
3. Create a basic Workflow and use the `helloWorld` Card. It will return a greeting message.

## What's Next?

For a better guide on how to integrate your integration with external messaging channels, check out the [Integration for Messaging Channels](./messaging) page.

For a more in-depth explanation of integration definition concepts, check out the [Integration Concepts](./concepts) page.


# Integration for Messaging Channels
Source: https://botpress.com/docs/integrations/sdk/integration/messaging



## How It Works

One of the most powerful features of Botpress Integrations is the ability to connect to external messaging channels. Without an integration, your bot can't receive or send messages—every message must go through an Integration.

Here's a high-level overview of how messaging works in Botpress:

```mermaid theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
sequenceDiagram
    actor U as End User
    participant ES as External Service
    participant I as Integration
    participant BP as Botpress
    participant Bot as Bot 🤖

    U ->>   ES:  Sends Message
    ES ->>  BP:  POST webhook.botpress.cloud/$webhookId
    BP ->>  I:   Forward webhook request
    I ->>   BP:  POST <br/>api.botpress.cloud<br/>/v1/chat/messages
    BP ->>  Bot: Forward created message
    Bot ->> BP:  POST <br/>api.botpress.cloud<br/>/v1/chat/messages
    BP ->>  I:   Forward outgoing messages
    I ->>   ES:  Forward outgoing messages
    ES ->>  U:   Display response
```

Here's a quick breakdown of the sequence:

1. The **end user** sends a message to an **external service** (e.g., WhatsApp, Messenger).
2. The **external service** forwards the message to **Botpress** via a webhook URL (e.g., `webhook.botpress.cloud/$webhookId`). Every integration has a unique way of providing the webhook URL to the external service. For example, Telegram does it using the API, while Slack requires you to set up a webhook URL in the Slack app settings. The webhook ID path parameter is a string that uniquely identifies the pair of an integration and a bot. This ID is different if you install the same integration in multiple different bots.
3. **Botpress** forwards the request to the **integration**, adding context like the bot ID.
4. The **integration** creates an incoming message using the [Botpress Runtime API](../../../api-reference/runtime-api/getting-started) at `api.botpress.cloud/v1/chat`.

<Note>
  The Runtime API requires authentication as either a Bot or an Integration.

  * Messages created by an **integration** are considered **incoming**.
  * Messages created by a **bot** are considered **outgoing**.
</Note>

5. **Botpress** forwards the created message to the **bot**.
6. The **bot** processes the message and responds via the Runtime API.
7. **Botpress** forwards the **outgoing message** to the **integration**.
8. The **integration** then sends the response back to the **external service**, which displays it to the **user**.

## Connect Your Own Channels

If Botpress doesn’t yet provide an integration for your preferred messaging service, you can create your own using the `webhook-message` template.

Follow the [Getting Started](./getting-started) guide and select the `webhook-message` template instead of `hello-world`.

### Integration Definition

After initializing your project, you'll see the following integration definition:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// integrations.definition.ts
import { z, IntegrationDefinition } from '@botpress/sdk'

export default new IntegrationDefinition({
  name: "webhook-message",
  version: '0.0.1',
  configuration: {
    schema: z.object({
      webhookUrl: z.string().describe('The url to post the bot answers to.'),
    }),
  },
  channels: {
    webhook: {
      conversation: {
        tags: {
          id: { title: 'Conversation ID', description: 'The ID of the conversation in the external service' },
        },
      },
      messages: {
        // this channel only supports text messages
        text: {
          schema: z.object({
            text: z.string(),
          }),
        },
      },
    },
  },
  user: {
    tags: {
      id: { title: 'User ID', description: 'The ID of the user in the external service' },
    },
  },
})
```

Let's break down this data structure:

* **`configuration`**: Defines the settings bot developers must provide when installing the integration in the Studio. The configuration schema is used to display a configuration form. Here, only a `webhookUrl` is required to receive outgoing messages.
* **`channels`**: Specifies supported messaging channels. This example uses a single `webhook` channel, but you can define multiple. For example, GitHub allows conversing with your bot on issues and pull requests. Each channel can have its own set of tags and message types.
* **`channels["$CHANNEL_NAME"].conversation.tags`**: Defines available tags for the conversation. In this case, we're defining a single tag called `id` that identifies the conversation in the external service. This allows binding the Botpress conversation to the external service conversation. When sending outgoing message response, this tag will be used to properly route the message to the external service.
* **`user.tags`**: Defines available tags for the user. Here, we define a single tag called `id` that identifies the user in the external service. This allows binding the Botpress user to the external service user.
* **`messages`**: Defines available message types. In this case, we're defining a single message type called `text` that contains a single field called `text`. This allows sending text messages to the external service. You could define multiple message types, for example, `image`, `video`, etc. The SDK exports a record of default message types that are supported in most messaging channels.

### Integration Implementation

The integration implementation looks something like this:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import * as sdk from '@botpress/sdk'
import axios from 'axios'
import * as bp from '.botpress'

export default new bp.Integration({
  register: async () => {},
  unregister: async () => {},
  actions: {},
  channels: {
    webhook: {
      messages: {
        text: async (props) => {
          // This is the outgoing message handler. It's called when a bot sends a message to the user.
          const {
            ctx: {
              configuration: { webhookUrl },
            },
            conversation: {
              id: botpressConversationId,
              tags: { id: externalConversationId },
            },
            payload: { text },
          } = props

          props.logger.forBot().debug(`[${botpressConversationId}] sending message "${text}"`)

          const requestBody = {
            conversationId: externalConversationId,
            text,
          }

          await axios.post(webhookUrl, requestBody)
        },
      },
    },
  },
  handler: async (props) => {
    // This is the incoming request handler. It's called by the external service you are integrating with.
    const {
      client,
      req: { body },
    } = props

    if (!body) {
      return {
        status: 400,
        body: JSON.stringify({ error: 'No body' }),
      }
    }

    let parsedBody: unknown
    try {
      parsedBody = JSON.parse(body)
    } catch {
      return {
        status: 400,
        body: JSON.stringify({ error: 'Invalid JSON Body' }),
      }
    }

    const parseResult = sdk.z
      .object({
        userId: sdk.z.string(),
        conversationId: sdk.z.string(),
        text: sdk.z.string(),
      })
      .safeParse(parsedBody)

    if (!parseResult.success) {
      return {
        status: 400,
        body: JSON.stringify({ error: 'Invalid body' }),
      }
    }

    const { userId, conversationId, text } = parseResult.data

    const { conversation } = await client.getOrCreateConversation({
      channel: 'webhook',
      tags: {
        id: conversationId,
      },
    })

    const { user } = await client.getOrCreateUser({
      tags: {
        id: userId,
      },
    })

    const { message } = await client.createMessage({
      type: 'text',
      conversationId: conversation.id,
      userId: user.id,
      payload: {
        text,
      },
      tags: {},
    })

    const response = {
      message,
    }

    return {
      status: 200,
      body: JSON.stringify(response),
    }
  },
})
```

Let's break down this code:

The `handler` function is where the incoming request is handled. When you or an external service calls `webhook.botpress.cloud/$webhookId` this is where Botpress forwards the request to.

The first thing done in this handler is always to parse the HTTP request. Once the request is parsed and validated you can see three consecutive calls made to the runtime API, respectively `getOrCreateConversation`, `getOrCreateUser`, and `createMessage`. This is a very common pattern in Botpress integrations that integrate with a messaging channel.

The `getOrCreateConversation` and `getOrCreateUser` operations first check if a conversation or user already exist for the provided tags (here the external ids). If they do, the operations return the existing conversation and user. If they don't, the operations create a new conversation and user with the provided tags. This ensures that subsequent messages from the same user and conversation are routed to the same conversation and user in Botpress.

The `createMessage` operation creates a new message in Botpress with the provided payload. This message is then forwarded to the bot for processing.

The `channels["$CHANNEL_NAME"]` property (here the channel name is `webhook`) is where you define the outgoing message handlers; i.e. the logic executed when the bot sends a message to the user. In this case, we're defining a single handler for the `text` message type. Here we call the configured webhook with the conversation that was created in the incoming request. It's important here not to confuse the id tag and the conversation id. The id tag is the external id of the conversation in the external service that was provided in the incoming request.

## What's Next?

Still unsure how integration messaging works? Here are some helpful resources:

* 📦 [Botpress GitHub Repository](https://github.com/botpress/botpress) - Most of our integrations source code is open source and can be found there.
* 📚 [Runtime API Docs](../../../api-reference/runtime-api/getting-started)—This documentation repeats a lot of information mentioned here but from the perspective of the server.
* 🧠 [Integration Concepts](./concepts)—Get deeper insight into integration concepts.


# Publish your integration on Botpress Hub
Source: https://botpress.com/docs/integrations/sdk/integration/publish-your-integration-on-botpress-hub



When you're ready to share your integration, you can publish it on [Botpress Hub](https://botpress.com/docs/card-hub). This will make your integration publicly available to other Botpress users.

## Publish your integration

<Steps>
  <Step title="Make your integration public">
    1. From the Dashboard, navigate to integration's page.
    2. Select **Make Public**:
       <img alt="image" />
    3. Accept the Hub terms and conditions.
  </Step>

  <Step title="Verify your integration">
    After making your bot public, you need to send it to Botpress for verification and approval.

    <Tip>
      Visual learner? Check out our [YouTube guide](https://www.youtube.com/embed/QJbqatyXfwI) on verifying your integration.
    </Tip>

    1. Update your profile on Botpress.
    2. Update your integration's display information.
    3. Ensure your integration asks users for any configuration parameters.
    4. Prepare an example bot that uses your integration.
    5. Send us your bot for approval.
  </Step>
</Steps>

## Your workspace profile on Botpress Hub

When a user installs your app, your workspace information will be viewable by the user. Please ensure:

1. [ ] Your Workspace has a URL handle that represents you.
2. [ ] You have a way for users to contact you, like an email or a website.
3. [ ] Introduce yourself in the Workspace description (optional). This is the place for self-promotion.
4. [ ] Add an icon to your Workspace that represents you (optional).

We suggest you create a Workspace specifically for publishing integrations, as this will make it easier to add collaborators to your workspace, and keep your production and development environments separate.

<img />

## Your integration's public information

<Warning>
  Don't include "Botpress" in your integration's title or use the Botpress logo in your icon. Also, self-promotion isn't allowed in the Hub.
</Warning>

Now we need to ensure the integration has all the assets and information it needs to be displayed on the Hub.

Your integration's definition file `integration.definition.ts` file should contain:

1. [ ] **title**: The display title of your integration for the hub.
2. [ ] **description**: A succinct description of what your integration does.
3. [ ] **icon**: The path to your SVG icon (usually `icon.svg`).
4. [ ] **README**: The path to your integration's README (usually `hub.md`).

Make sure to have an icon and a README in the root of your integration folder:

1. [ ] **icon.svg**: Use a pertinent icon related to the problem you are solving.
2. [ ] **hub.md**: It should contain an explanation of what the integration is, how to configure it, and how to use it. Please include a link to your git repository if your integration is open source—this drastically increases your chances of getting approved.

## Your integration's logic

Finally, we need to ensure your integration is robust and user-friendly.

1. [ ] If your integration requires parameters to be configured: it should validate the parameters in the register method, and throw a `RuntimeError` if there is an issue.

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import * as bpclient from "@botpress/client";

[...]

throw new RuntimeError(
	"Configuration Error! The Mixpanel token isn't set. Please set it in your bot integration configuration."
);
```

This `RuntimeError` will be shown to the user in the Botpress Studio when they try to add your integration to their bot and there is an issue.

## Submitting your integration for verification

When you're done with above, we'd like to test your integration to ensure it works as expected, and that everything is in order. Whenever you're ready , just click the `Request Verification` button on the banner.

<img />

To speed up the process, you can do the following proactively

1. [ ] In your workspace, create a demonstration bot and configure your integration for it. We'll use this to try out the integration.
2. [ ] Add `hub-applications@botpress.com` to your workspace with Admin privileges.


# Use your own LLM
Source: https://botpress.com/docs/integrations/sdk/integration/use-your-own-llm



<Note>
  Using your own LLM is available on [Enterprise plans](https://botpress.com/pricing). To get started with your own LLM, [contact our sales team](https://botpress.com/contact-us?ref=navbar).
</Note>

You can use the Botpress SDK to **integrate your own LLM**, giving you full control over the intelligence powering your AI agents.

Bringing your own LLM can unlock greater flexibility and performance for your bot. You can:

* Fine-tune your model for your industry
* Align the model's tone and behaviour with your brand
* Scale cost-effectively and extend your existing AI infrastructure

<Tip>
  If you're an LLM provider and are interested in monetizing your own LLM by making it available for use on Botpress, [contact us.](https://botpress.com/contact-us)
</Tip>


# How to implement an interface in your integration
Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/add-and-implement



## Finding the interface to implement

Unfortunately, interfaces aren't yet listed on our website, so you must find them in the Botpress GitHub repository. To find the interface you want to implement, follow these steps:

<Steps>
  <Step title="Open the interfaces directory">
    Navigate to the [`interfaces` directory](https://github.com/botpress/botpress/tree/master/interfaces) of the [botpress/botpress](https://github.com/botpress/botpress) repository.
  </Step>

  <Step title="Find the interface">
    Find the interface you want to implement and open its directory.
  </Step>

  <Step title="Find the name and version">
    Open the `interface.definition.ts` file to find the interface `name` and `version`.
  </Step>
</Steps>

## Adding the interface as a dependency

Once you have the interface name and version, you can add it as a dependency to your integration:

<Steps>
  <Step title="Open the package.json file">
    Open your integration's `package.json` file.
  </Step>

  <Step title="Add the dependencies section">
    If there is no `bpDependencies` section in your integration's `package.json` file, create one:

    ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "bpDependencies": {}
    }
    ```
  </Step>

  <Step title="Add the interface as a dependency">
    In the `bpDependencies` section, add the interface name and version as a dependency. For example, with an interface named `creatable` and version `0.0.1`, you would add the following:

    ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "bpDependencies": {
        "creatable": "interface:creatable@0.0.1"
      }
    }
    ```

    <Warning>
      It's very important to follow this syntax: <br />
      `"<interface-name>": "interface:<interface-name>@<version>"`.
    </Warning>
  </Step>

  <Step title="Save the package.json file">
    Save the `package.json` file.
  </Step>

  <Step title="Install the interface">
    Now that you have added the interface as a dependency, you can run the [`bp add`](/docs/integrations/sdk/cli-reference#add) command to install it. This command will:

    * Download the interface from Botpress.
    * Install it in a directory named `bp_modules` in your integration's root directory.
  </Step>
</Steps>

## Adding a helper build script

To keep your integration up to date, we recommend adding a helper build script to your integration:

<Steps>
  <Step title="Open the package.json file">
    Open your integration's `package.json` file.
  </Step>

  <Step title="Add the build script">
    In the `scripts` section, add the following script:

    ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "scripts": {
        "build": "bp add -y && bp build"
      }
    }
    ```

    <Note>
      If the `build` script already exists in your `package.json` file, please replace it.
    </Note>
  </Step>

  <Step title="Save the package.json file">
    Save the `package.json` file.
  </Step>
</Steps>

Now, whenever you run `npm run build`, it will automatically install the interface and build your integration. This is useful for ensuring that your integration is always up to date with the latest version of the interface.

## Adding the interface to your integration definition file

Now that the interface is installed, you must add it your integration definition file in order to implement it.

<Steps>
  <Step title="Open the integration.definition.ts file">
    Open your integration's `integration.definition.ts` file.
  </Step>

  <Step title="Import the interface">
    At the top of the file, import the interface. For example, with an interface named `creatable`, you would add the following import statement:

    ```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    import creatable from './bp_modules/creatable'
    ```
  </Step>

  <Step title="Extend your definition">
    Use the `.extend()` function at the end of your `new IntegrationDefinition()` statement. For example, with an interface named `creatable`, you would add the following:

    ```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    export default new sdk.IntegrationDefinition({
      ...
    })
      .extend(creatable, () => ({}))
    ```
  </Step>
</Steps>

## Next steps

Since each interface has its own specific requirements, you should refer to the interface documentation for more information.

<CardGroup>
  <Card icon={<HitlIcon />} title="Human in the loop" href="/integrations/sdk/interface/how-tos/implementing-hitl">
    How to implement Human in the loop
  </Card>
</CardGroup>


# Implementing unidirectional file synchronization in an integration
Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/implementing-file-sync



<p>
  <FileSynchronizerIcon />

  The unidirectional file synchronization interface allows you to implement 1-way sync in your integration to import files from an external service to Botpress.
</p>

## Filesystem abstraction

The file synchronization interface provides a filesystem-like abstraction that works with any kind of data source. The external service doesn't need to provide an actual filesystem - your integration just needs to represent the external data as files and folders.

For example:

* If you are building a website crawler, individual pages could be folders and HTML contents and assets like images or stylesheets could be files.
* For a note-taking platform, notebooks could be folders with individual notes being files.
* For an email provider, mailboxes or labels could be folders and individual emails could be files.

This abstraction allows the interface to work consistently regardless of what type of data is being synchronized from your external service.

## Terminology

Throughout this document, we will use the following terms:

<DefinitionList>
  <Definition>
    The code that connects Botpress to an external service.
  </Definition>

  <Definition>
    The service from which you want to import files. This could be a cloud storage service, a file server, or any other type of external service that stores files.
  </Definition>

  <Definition>
    The interface that defines the contract for implementing unidirectional file synchronization in your integration. This interface specifies the actions and events that your integration must implement to support file synchronization.
  </Definition>

  <Definition>
    The Botpress plugin that orchestrates file synchronization. This plugin is responsible for managing the synchronization process, including scheduling, error handling, and reporting.
  </Definition>

  <Definition>
    A file is a single unit of data that can be synchronized from the external service to Botpress. Files can contain any type of data, such as text, images, or binary data. Files can't contain other files or folders.
  </Definition>

  <Definition>
    A folder is a container for files. Folders can contain other folders and files, allowing for a hierarchical organization of data.
  </Definition>

  <Definition>
    A synchronization mode where changes in the external service are immediately reflected in Botpress. This is typically achieved through webhooks or other push mechanisms. Integrations aren't required to support this mode, but it's recommended for better user experience.
  </Definition>
</DefinitionList>

## External service requirements

The <DefinitionReference /> providing file synchronization functionality **must** support the following:

* An API that allows listing all files and folders in a folder.
  * Must support pagination. This means that the API should return a limited number of items at a time, along with a token that can be used to retrieve the next set of items.
* An API that allows downloading files.

The <DefinitionReference /> **may** also support the following in order to provide <DefinitionReference />:

* Webhooks that can notify your <DefinitionReference /> of the following events:
  * A <DefinitionReference /> was created.
  * A <DefinitionReference /> was updated.
  * A <DefinitionReference /> was deleted.
  * A <DefinitionReference /> was deleted.

## Updating your `package.json` file

### Finding the current interface version

The current version of the `files-readonly` interface is: <code><CurrentInterfaceVersion /></code>

You will need this version number for the next steps.

### Adding the interface as a dependency

Once you have the <DefinitionReference /> version, you can add it as a dependency to your <DefinitionReference />:

<Steps>
  <Step title="Open the package.json file">
    Open your <DefinitionReference />'s `package.json` file.
  </Step>

  <Step title="Add the dependencies section">
    If there is no `bpDependencies` section in your <DefinitionReference />'s `package.json` file, create one:

    ```json package.json {2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "bpDependencies": {}
    }
    ```
  </Step>

  <Step title="Add the interface as a dependency">
    In the `bpDependencies` section, add the <DefinitionReference /> as a dependency. For example, for version `0.2.0`, you would add the following:

    ```json package.json {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "bpDependencies": {
        "files-readonly": "interface:files-readonly@0.2.0"
      }
    }
    ```

    <Warning>
      It's very important to follow this syntax: <br />
      `"<interface-name>": "interface:<interface-name>@<version>"`.
    </Warning>
  </Step>

  <Step title="Save the package.json file">
    Save the `package.json` file.
  </Step>

  <Step title="Install the interface">
    Now that you have added the <DefinitionReference /> as a dependency, you can run the [`bp add`](/docs/integrations/sdk/cli-reference#add) command to install it. This command will:

    * Download the interface from Botpress.
    * Install it in a directory named `bp_modules` in your <DefinitionReference />'s root directory.
  </Step>
</Steps>

### Adding a helper build script

To keep your <DefinitionReference /> up to date, we recommend adding a helper build script to your `package.json` file:

<Steps>
  <Step title="Open the package.json file">
    Open your <DefinitionReference />'s `package.json` file.
  </Step>

  <Step title="Add the build script">
    In the `scripts` section, add the following script:

    ```json package.json {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "scripts": {
        "build": "bp add -y && bp build"
      }
    }
    ```

    <Note>
      If the `build` script already exists in your `package.json` file, please replace it.
    </Note>
  </Step>

  <Step title="Save the package.json file">
    Save the `package.json` file.
  </Step>
</Steps>

Now, whenever you run `npm run build`, it will automatically install the <DefinitionReference /> and build your <DefinitionReference />.

## Editing your integration definition file

### Adding the interface to your integration definition file

Now that the <DefinitionReference /> is installed, you must add it your integration definition file in order to implement it.

<Steps>
  <Step title="Open the integration.definition.ts file">
    Open your <DefinitionReference />'s `integration.definition.ts` file.
  </Step>

  <Step title="Import the interface">
    At the top of the file, import the <DefinitionReference />:

    ```typescript integration.definition.ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    import filesReadonly from './bp_modules/files-readonly'
    ```
  </Step>

  <Step title="Extend your definition">
    Use the `.extend()` function at the end of your `new IntegrationDefinition()` statement:

    ```typescript integration.definition.ts {4-6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    export default new sdk.IntegrationDefinition({
      ...
    })
      .extend(files-readonly, () => ({
        entities: {},
      }))
    ```

    The exact syntax of `.extend()` will be explained in the next section.
  </Step>
</Steps>

### Configuring the interface

The `.extend()` function takes two arguments:

* The first argument is a reference to the interface you want to implement. In this case, it's `filesReadonly`.
* The second argument is a configuration object. Using this object, you can override interface defaults with custom names, titles, and descriptions.

<Tip>
  Whilst renaming actions, events and channels is optional, it's highly recommended to rename these to match the terminology of the <DefinitionReference />. This will help you avoid confusion and make your <DefinitionReference /> easier to understand.
</Tip>

#### Renaming actions

The <DefinitionReference /> defines two actions that are used to interact with the <DefinitionReference />:

* `listItemsInFolder` - Used by the <DefinitionReference /> to request a list of all files and folders in a folder.
* `transferFileToBotpress` - Used by the <DefinitionReference /> to request that a file be downloaded from the <DefinitionReference /> and uploaded to Botpress.

If you want to rename these actions, you can do so in the configuration object. For example, if you want to rename `listItemsInFolder` to `crawlFolder`, you can do it like this:

```typescript integration.definition.ts {4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.extend(filesReadonly, () => ({
  actions: {
    listItemsInFolder: {
      name: 'crawlFolder',
    },
  },
}))
```

<Tip>
  For example, if you're using a note-taking platform such as Microsoft OneNote, you might rename `listItemsInFolder` to `listNotebooksAndPages` and `transferFileToBotpress` to `downloadPage`. This way, the action names reflect the specific context of the note-taking platform, making your <DefinitionReference /> clearer and easier to understand.
</Tip>

#### Renaming events

The <DefinitionReference /> interface defines these events to notify the plugin of changes in the <DefinitionReference />:

* `fileCreated` - Emitted by your <DefinitionReference /> to notify the <DefinitionReference /> that a new <DefinitionReference /> has been created in the <DefinitionReference />.
* `fileUpdated` - Emitted by your <DefinitionReference /> to notify the <DefinitionReference /> that a <DefinitionReference /> has been updated in the <DefinitionReference />.
* `fileDeleted` - Emitted by your <DefinitionReference /> to notify the <DefinitionReference /> that a <DefinitionReference /> has been deleted in the <DefinitionReference />.
* `folderDeletedRecursive` - Emitted by your <DefinitionReference /> to notify the <DefinitionReference /> that a <DefinitionReference /> and all of its contents have been deleted in the <DefinitionReference />.

<Tip>
  If the <DefinitionReference /> emits several filesystem changes at once, it's also possible for your integration to emit a `aggregateFileChanges` event, which contains all the changes in a single event.
</Tip>

If you want to rename these events, you can do so in the configuration object. For example, if you want to rename `fileCreated` to `pageCreated`, you can do it like this:

```typescript integration.definition.ts {4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.extend(filesReadonly, () => ({
  events: {
    fileCreated: {
      name: 'pageCreated',
    },
  },
}))
```

## Implementing the interface

### Implementing the actions

#### Implementing `listItemsInFolder`

The `listItemsInFolder` action is used by the <DefinitionReference /> to request a list of all files and folders in a folder.

<Note>
  If you opted to rename the action to something else to `listItemsInFolder` in the "Configuring the interface" section, please use the new name instead of `listItemsInFolder`.
</Note>

Please refer to the expected input and output schemas for the action:
[interface.definition.ts line 52](https://github.com/botpress/botpress/blob/master/interfaces/files-readonly/interface.definition.ts#L52).

This action should implement the following logic:

<Steps>
  <Step title="Get the folder ID">
    Get the folder identifier from `input.folderId`. When this value is `undefined`, it means the <DefinitionReference /> is requesting a list of all items in the root directory of the <DefinitionReference />. For root directory requests, please refer to the documentation of the <DefinitionReference /> to determine the correct root identifier - this is typically an empty string, a slash character (`/`), or a special value defined by the service.
  </Step>

  <Step title="Get the list of items">
    Use the <DefinitionReference />'s API to get the list of items in the folder. If the <DefinitionReference /> supports filtering by item type (file or folder), by maximum file size, or by modification date, please use these filters to limit the number of items returned. This will help reduce the amount of data transferred and improve performance.

    <Expandable title="item filters">
      ```typescript {3-7} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type Input = {
        folderId?: string;
        filters?: {
          itemType?: "file" | "folder";
          maxSizeInBytes?: number;
          modifiedAfter?: string; // <= ISO 8601 date string
        };
        nextToken?: string; // <= pagination token
      };
      ```
    </Expandable>

    <Note>
      If a pagination token is provided (`input.nextToken`), use it to get the next page of items. The <DefinitionReference /> should return a new pagination token in the response, which you should return with the action's response.
    </Note>

    <Warning>
      **Don't** list items recursively. The <DefinitionReference /> is responsible for handling recursion. Your <DefinitionReference /> should only return the items in the specified folder.
    </Warning>
  </Step>

  <Step title="Map each items to the expected schema">
    Map each item to the expected schema. The <DefinitionReference /> expects the following schemas:

    <Expandable title="folder schema">
      ```typescript {2-4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type Folder = {
        id: string;
        type: "folder";
        name: string;
        parentId?: string;
        absolutePath?: string;
      }
      ```

      <ResponseField name="id" type="string">
        This could be a unique identifier from the <DefinitionReference />, or a relative or absolute path, so long as it's unique. Your <DefinitionReference /> must be able to resolve this identifier to the actual folder in the <DefinitionReference />. The <DefinitionReference /> will use this identifier to enumerate children of this folder.
      </ResponseField>

      <ResponseField name="type" type="string">
        This should always be `folder`.
      </ResponseField>

      <ResponseField name="name" type="string">
        The name of the folder. This should be the name of the folder as it appears in the <DefinitionReference />.
      </ResponseField>

      <ResponseField name="parentId" type="string">
        The identifier of the parent folder. This should be the same identifier as the one used in the `folderId` field of the input.
      </ResponseField>

      <ResponseField name="absolutePath" type="string">
        The absolute path of the folder in the <DefinitionReference />, if available.
      </ResponseField>
    </Expandable>

    <Expandable title="file schema">
      ```typescript {2-4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type File = {
        id: string;
        type: "file";
        name: string;
        parentId?: string;
        absolutePath?: string;
        sizeInBytes?: number;
        lastModifiedDate?: string;
        contentHash?: string;
      }
      ```

      <ResponseField name="id" type="string">
        This could be a unique identifier from the <DefinitionReference />, or a relative or absolute path, so long as it's unique. Your <DefinitionReference /> must be able to resolve this identifier to the actual file in the <DefinitionReference />. The <DefinitionReference /> will use this identifier to download the file.
      </ResponseField>

      <ResponseField name="type" type="string">
        This should always be `file`.
      </ResponseField>

      <ResponseField name="name" type="string">
        The name of the file. This should be the name of the file as it appears in the <DefinitionReference />, including its file extension. This same name will be used to display the file in Botpress.
      </ResponseField>

      <ResponseField name="parentId" type="string">
        The identifier of the parent folder. This should be the same identifier as the one used in the `folderId` field of the input.
      </ResponseField>

      <ResponseField name="absolutePath" type="string">
        The absolute path of the file in the <DefinitionReference />, if available.
      </ResponseField>

      <ResponseField name="sizeInBytes" type="number">
        The size of the file in bytes, if available.
      </ResponseField>

      <ResponseField name="lastModifiedDate" type="string">
        The last modified date of the file, if available. This should be an ISO 8601 date string.
      </ResponseField>

      <ResponseField name="contentHash" type="string">
        The content hash of the file, if available. This should be a unique identifier for the file's content, such as an MD5 or SHA-1 hash.
        This is used to detect changes in the file's content. If the content hash isn't available but the <DefinitionReference /> provides a version or revision number, you can use that instead.
      </ResponseField>
    </Expandable>
  </Step>

  <Step title="Yield control back to the plugin">
    Yield control back to the <DefinitionReference /> by returning the list of items. The <DefinitionReference /> will then handle the rest of the synchronization process.

    ```typescript {2-3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    return {
      items: [...mappedFolders, ...mappedFiles],
      meta: { nextToken: hasMoreItems ? nextToken : undefined },
    }
    ```

    <Note>
      If the <DefinitionReference /> indicates it has more items, return the pagination token in the `nextToken` field. The <DefinitionReference /> will use this token to request the next page of items. Otherwise, return `undefined`.
    </Note>
  </Step>
</Steps>

As reference, here's how this logic is implemented in the Dropbox integration:

```typescript src/index.ts {4,7,11,14,15,20,27} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  actions: {
    async listItemsInFolder({ ctx, input, client }) {
      // Extract input parameters:
      const { folderId, filters, nextToken: prevToken } = input

      // Get the folder ID:
      //    (Dropbox expects an empty string for the root directory)
      const parentId = folderId ?? ''

      // Get the list of items in the folder
      const { items, nextToken, hasMore } = await dropboxClient.listItemsInFolder({
        path: parentId,
        recursive: false, // <= The integration shouldn't list recursively
        nextToken: prevToken, // <= Use the pagination token if provided
      })

      const mappedItems = items
        .filter((item) => item.itemType !== 'deleted')
        // Call utility functions to handle the mapping:
        .map((item) =>
          item.itemType === 'file' ?
            filesReadonlyMapping.mapFile(item) :
            filesReadonlyMapping.mapFolder(item)
        )

      // Yield control back to the plugin and return the items:
      return {
        items: mappedItems,
        meta: { nextToken: hasMore ? nextToken : undefined },
      }
    },
  },
})
```

#### Implementing `transferFileToBotpress`

The `transferFileToBotpress` action is used by the <DefinitionReference /> to request that a file be downloaded from the <DefinitionReference /> and uploaded to Botpress.

<Note>
  If you opted to rename the action to something else to `transferFileToBotpress` in the "Configuring the interface" section, please use the new name instead of `transferFileToBotpress`.
</Note>

Please refer to the expected input and output schemas for the action:
[interface.definition.ts line 88](https://github.com/botpress/botpress/blob/master/interfaces/files-readonly/interface.definition.ts#L88).

This action should implement the following logic:

<Steps>
  <Step title="Get the file ID">
    Get the file identifier from `input.file.id`. This is the identifier of the file to be downloaded from the <DefinitionReference />.
  </Step>

  <Step title="Download the file from the external service">
    Use the <DefinitionReference />'s API to download the file's content.
  </Step>

  <Step title="Upload the file to Botpress">
    Upload the file to Botpress using the `client.uploadFile` method. This method expects both the file's content and a file key, which is provided by the <DefinitionReference /> as `input.fileKey`.
  </Step>

  <Step title="Yield control back to the plugin">
    Yield control back to the <DefinitionReference /> by returning the ID of the file that was uploaded to Botpress.
  </Step>
</Steps>

As reference, here's how this logic is implemented in the Dropbox integration:

```typescript src/index.ts {4,7,10,16} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  actions: {
    async transferFileToBotpress({ ctx, input, client }) {
      // Extract input parameters:
      const { file: fileToTransfer, fileKey } = input

      // Use Dropbox's SDK to download the file:
      const fileBuffer = await dropboxClient.getFileContents({ path: fileToTransfer.id })

      // Upload the file to Botpress:
      const { file: uploadedFile } = await client.uploadFile({
        key: fileKey,
        content: fileBuffer,
      })

      // Yield control back to the plugin:
      return {
        botpressFileId: uploadedFile.id
      }
    },
  },
})
```

### Implementing real-time sync

The <DefinitionReference /> can be configured to use real-time synchronization. This means that changes in the <DefinitionReference /> are immediately reflected in Botpress. To enable this functionality, the <DefinitionReference /> must support webhooks that can notify your <DefinitionReference /> of changes in the filesystem.

#### Implementing `fileCreated`

<Steps>
  <Step title="Add a webhook handler">
    In your <DefinitionReference />, add a webhook handler that can receive file change notifications from the <DefinitionReference />.
  </Step>

  <Step title="Map the file to the expected schema">
    In your handler, map the file to the expected schema. The <DefinitionReference /> expects the following schema:

    <Expandable title="file schema">
      ```typescript {2-5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type File = {
        id: string;
        type: "file";
        name: string;
        absolutePath: string;
        parentId?: string;
        sizeInBytes?: number;
        lastModifiedDate?: string;
        contentHash?: string;
      }
      ```

      <ResponseField name="id" type="string">
        This could be a unique identifier from the <DefinitionReference />, or a relative or absolute path, so long as it's unique. Your <DefinitionReference /> must be able to resolve this identifier to the actual file in the <DefinitionReference />. The <DefinitionReference /> will use this identifier to download the file.
      </ResponseField>

      <ResponseField name="type" type="string">
        This should always be `file`.
      </ResponseField>

      <ResponseField name="name" type="string">
        The name of the file. This should be the name of the file as it appears in the <DefinitionReference />, including its file extension. This same name will be used to display the file in Botpress.
      </ResponseField>

      <ResponseField name="absolutePath" type="string">
        The absolute path of the file in the <DefinitionReference />. Unlike with the `listItemsInFolder` action, this field is required for the `fileCreated` event.
      </ResponseField>

      <ResponseField name="parentId" type="string">
        The identifier of the parent folder.
      </ResponseField>

      <ResponseField name="sizeInBytes" type="number">
        The size of the file in bytes, if available.
      </ResponseField>

      <ResponseField name="lastModifiedDate" type="string">
        The last modified date of the file, if available. This should be an ISO 8601 date string.
      </ResponseField>

      <ResponseField name="contentHash" type="string">
        The content hash of the file, if available. This should be a unique identifier for the file's content, such as an MD5 or SHA-1 hash.
        This is used to detect changes in the file's content. If the content hash isn't available but the <DefinitionReference /> provides a version or revision number, you can use that instead.
      </ResponseField>
    </Expandable>
  </Step>

  <Step title="Emit the event">
    Emit the `fileCreated` event with the mapped file as the payload. The <DefinitionReference /> will then handle the rest of the synchronization process.

    ```typescript {2-3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    await client.createEvent({
      name: 'fileCreated',
      payload: { file: mappedFile },
    })
    ```
  </Step>
</Steps>

#### Implementing `fileUpdated`

The logic is identical to the `fileCreated` event, but you should emit the `fileUpdated` event instead.

#### Implementing `fileDeleted`

The logic is identical to the `fileCreated` event, but you should emit the `fileDeleted` event instead.

#### Implementing `folderDeletedRecursive`

<Steps>
  <Step title="Add a webhook handler">
    In your <DefinitionReference />, add a webhook handler that can receive file change notifications from the <DefinitionReference />.
  </Step>

  <Step title="Map the folder to the expected schema">
    In your handler, map the folder to the expected schema. The <DefinitionReference /> expects the following schema:

    <Expandable title="folder schema">
      ```typescript {2-5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      type Folder = {
        id: string;
        type: "folder";
        name: string;
        absolutePath: string;
        parentId?: string;
      }
      ```

      <ResponseField name="id" type="string">
        This could be a unique identifier from the <DefinitionReference />, or a relative or absolute path, so long as it's unique.
      </ResponseField>

      <ResponseField name="type" type="string">
        This should always be `folder`.
      </ResponseField>

      <ResponseField name="name" type="string">
        The name of the folder. This should be the name of the folder as it appears in the <DefinitionReference />
      </ResponseField>

      <ResponseField name="absolutePath" type="string">
        The absolute path of the folder in the <DefinitionReference />. Unlike with the `listItemsInFolder` action, this field is required for the `folderDeletedRecursive` event.
      </ResponseField>

      <ResponseField name="parentId" type="string">
        The identifier of the parent folder.
      </ResponseField>
    </Expandable>
  </Step>

  <Step title="Emit the event">
    Emit the `folderDeletedRecursive` event with the mapped folder as the payload. The <DefinitionReference /> will then handle the rest of the synchronization process.

    ```typescript {2-3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    await client.createEvent({
      name: 'folderDeletedRecursive',
      payload: { folder: mappedFolder },
    })
    ```
  </Step>
</Steps>

#### Implementing `aggregateFileChanges`

The logic is identical to the `fileCreated`, `fileUpdated`, `fileDeleted`, or `folderDeletedRecursive` events, but you should emit the `aggregateFileChanges` event instead:

```typescript {4-8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await client.createEvent({
  name: 'aggregateFileChanges',
  payload: {
    modifiedItems: {
      created: [...mappedCreatedFiles],
      updated: [...mappedUpdatedFiles],
      deleted: [...mappedDeletedFilesOrFolders],
    },
  },
})
```

<Tip>
  If your <DefinitionReference /> needs to emit more than one filesystem change event, you should combine them into a single `aggregateFileChanges` event. This is more efficient and faster to process for the <DefinitionReference />.
</Tip>


# Implementing Human in the loop (HITL) in an integration
Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/implementing-hitl



<p>
  <HitlIcon />

  The Human in the loop (HITL) interface allows you to implement human agent intervention in your integration.
</p>

## Terminology

Throughout this document, we will use the following terms:

<DefinitionList>
  <Definition>
    The code that connects Botpress to an external service.
  </Definition>

  <Definition>
    The service that provides HITL functionality. This could be a help desk system like Zendesk, or any other system that allows human agents to send and receive messages to end users.
  </Definition>

  <Definition>
    A person who interacts with end users through the external service. This could be a support agent, a sales representative, or any other type of human agent.
  </Definition>

  <Definition>
    A person who interacts with your bot through Botpress. This could be a customer, a user, an employee, or any other type of end user.
  </Definition>

  <Definition>
    A representation of an end user within the external service. This is typically created when a HITL session is started.
  </Definition>

  <Definition>
    A conversation between an end user and a human agent. This is typically represented as a *ticket* in the external service.
  </Definition>

  <Definition>
    The interface that defines the contract for implementing HITL functionality in your integration. This interface specifies the actions, events, and channels that your integration must implement to support HITL.
  </Definition>

  <Definition>
    The Botpress plugin that manages HITL sessions and relays messages between end users and your integration. Installing this plugin in a bot enables HITL functionality using the selected integration.
  </Definition>

  <Definition>
    In the context of the HITL interface and plugin, an entity can be provided in order to support extra parameters in the `startHitl` action. This is useful to provide extra information about the HITL session, such as a ticket priority or customer identification number.
  </Definition>
</DefinitionList>

## External service requirements

The <DefinitionReference /> providing HITL functionality **must** support the following:

* An API that allows creating <DefinitionReference />.
* An API that allows creating <DefinitionReference />.
* An API that allows adding messages to <DefinitionReference />.
* An API that allows closing <DefinitionReference />.
* Webhooks that can notify your <DefinitionReference /> of the following events:
  * <DefinitionReference /> closure.
  * <DefinitionReference /> assignment.
  * <DefinitionReference /> reply.

## Updating your `package.json` file

### Finding the current interface version

The current version of the `hitl` interface is: <code><CurrentInterfaceVersion /></code>

You will need this version number for the next steps.

### Adding the interface as a dependency

Once you have the <DefinitionReference /> version, you can add it as a dependency to your <DefinitionReference />:

<Steps>
  <Step title="Open the package.json file">
    Open your <DefinitionReference />'s `package.json` file.
  </Step>

  <Step title="Add the dependencies section">
    If there is no `bpDependencies` section in your <DefinitionReference />'s `package.json` file, create one:

    ```json package.json {2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "bpDependencies": {}
    }
    ```
  </Step>

  <Step title="Add the interface as a dependency">
    In the `bpDependencies` section, add the <DefinitionReference /> as a dependency. For example, for version `2.0.0`, you would add the following:

    ```json package.json {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "bpDependencies": {
        "hitl": "interface:hitl@2.0.0"
      }
    }
    ```

    <Warning>
      It's very important to follow this syntax: <br />
      `"<interface-name>": "interface:<interface-name>@<version>"`.
    </Warning>
  </Step>

  <Step title="Save the package.json file">
    Save the `package.json` file.
  </Step>

  <Step title="Install the interface">
    Now that you have added the <DefinitionReference /> as a dependency, you can run the [`bp add`](/docs/integrations/sdk/cli-reference#add) command to install it. This command will:

    * Download the interface from Botpress.
    * Install it in a directory named `bp_modules` in your <DefinitionReference />'s root directory.
  </Step>
</Steps>

### Adding a helper build script

To keep your <DefinitionReference /> up to date, we recommend adding a helper build script to your `package.json` file:

<Steps>
  <Step title="Open the package.json file">
    Open your <DefinitionReference />'s `package.json` file.
  </Step>

  <Step title="Add the build script">
    In the `scripts` section, add the following script:

    ```json package.json {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "scripts": {
        "build": "bp add -y && bp build"
      }
    }
    ```

    <Note>
      If the `build` script already exists in your `package.json` file, please replace it.
    </Note>
  </Step>

  <Step title="Save the package.json file">
    Save the `package.json` file.
  </Step>
</Steps>

Now, whenever you run `npm run build`, it will automatically install the <DefinitionReference /> and build your <DefinitionReference />.

## Editing your integration definition file

### Adding the interface to your integration definition file

Now that the <DefinitionReference /> is installed, you must add it your integration definition file in order to implement it.

<Steps>
  <Step title="Open the integration.definition.ts file">
    Open your <DefinitionReference />'s `integration.definition.ts` file.
  </Step>

  <Step title="Import the interface">
    At the top of the file, import the <DefinitionReference />:

    ```typescript integration.definition.ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    import hitl from './bp_modules/hitl'
    ```
  </Step>

  <Step title="Add an empty entity">
    In your `new IntegrationDefinition()` statement, add an empty entity:

    ```typescript integration.definition.ts {2-6} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    export default new sdk.IntegrationDefinition({
      entities: {
        ticket: {                     // <= name of the entity
          schema: sdk.z.object({})
        },
      },
    })
    ```

    <Note>
      The name of the entity isn't important, but it's recommended to use a name that matches the terminology of the <DefinitionReference />. For example, if the <DefinitionReference /> uses the term "ticket" to refer to a <DefinitionReference />, you could name the entity `ticket` or `hitlTicket`.
    </Note>
  </Step>

  <Step title="Extend your definition">
    Use the `.extend()` function at the end of your `new IntegrationDefinition()` statement:

    ```typescript integration.definition.ts {8-12} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    export default new sdk.IntegrationDefinition({
      entities: {
        ticket: {                     // <= name of the entity
          schema: sdk.z.object({})
        },
      },
    })
      .extend(hitl, (self) => ({
        entities: {
          hitlSession: self.entities.ticket, // <= name of the entity
        },
      }))
    ```

    The exact syntax of `.extend()` will be explained in the next section.
  </Step>
</Steps>

### Configuring the interface

The `.extend()` function takes two arguments:

* The first argument is a reference to the interface you want to implement. In this case, it's `hitl`.
* The second argument is a configuration object. Using this object, you can override interface defaults with custom names, titles, and descriptions.

<Tip>
  Whilst renaming actions, events and channels is optional, it's highly recommended to rename these to match the terminology of the <DefinitionReference />. This will help you avoid confusion and make your <DefinitionReference /> easier to understand.
</Tip>

#### Renaming actions

The `hitl` interface defines three actions that are used to interact with the <DefinitionReference />:

* `createUser` - Used by the <DefinitionReference /> to request the creation of a user in the <DefinitionReference /> and on Botpress.
* `startHitl` - Used by the <DefinitionReference /> to request the creation of a <DefinitionReference /> in the <DefinitionReference />.
* `stopHitl` - Used by the <DefinitionReference /> to request the closure of a <DefinitionReference /> in the <DefinitionReference />.

If you want to rename these actions, you can do so in the configuration object. For example, if you want to rename `createUser` to `hitlCreateUser`, you can do it like this:

```typescript integration.definition.ts {4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.extend(hitl, () => ({
  actions: {
    createUser: {
      name: 'hitlCreateUser',
    },
  },
}))
```

<Tip>
  For example, if you're using a *help desk* system like Zendesk, Jira Service Desk, or Freshdesk for HITL functionality, you might rename `startHitl` to `createTicket` and `stopHitl` to `closeTicket`. These systems use tickets to represent help requests, so renaming actions to match their terminology makes your <DefinitionReference /> clearer and easier to understand.
</Tip>

#### Renaming events

The `hitl` interface defines these events to notify the plugin of changes in the external service:

* `hitlAssigned` - Emitted by your <DefinitionReference /> to notify the <DefinitionReference /> that a <DefinitionReference /> has been assigned to a <DefinitionReference />.
* `hitlStopped` - Emitted by your <DefinitionReference /> to notify the <DefinitionReference /> that a <DefinitionReference /> has been closed.

If you want to rename these events, you can do so in the configuration object. For example, if you want to rename `hitlAssigned` to `agentAssigned`, you can do it like this:

```typescript integration.definition.ts {4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.extend(hitl, () => ({
  events: {
    hitlAssigned: {
      name: 'agentAssigned',
    },
  },
}))
```

#### Renaming channels

The `hitl` interface defines these channels:

* `hitl` - Used by the <DefinitionReference /> to send and receive messages from the <DefinitionReference />. This represents the communication channel for the <DefinitionReference />, like a support ticket on Zendesk or a direct message thread on Slack.

If you want to rename this channel, you can do so in the configuration object. For example, if you want to rename `hitl` to `supportTicket`, you can do it like this:

```typescript integration.definition.ts {4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.extend(hitl, () => ({
  channels: {
    hitl: {
      name: 'supportTicket',
    },
  },
}))
```

## Implementing the interface

### Implementing the actions

#### Implementing `createUser`

The `createUser` action is used by the <DefinitionReference /> to request the creation of an <DefinitionReference /> (a *requester*) in the <DefinitionReference />.

<Note>
  If you opted to rename the action to something else than `createUser` in the "Configuring the interface" section, please use the new name instead of `createUser`.
</Note>

Please refer to the expected input and output schemas for the action:
[interface.definition.ts line 85](https://github.com/botpress/botpress/blob/023d7de196e63f1a1b7cac0cf4f97c3d4aac940f/interfaces/hitl/interface.definition.ts#L85).

This action should implement the following logic:

<Steps>
  <Step title="Create a Botpress user">
    Create a Botpress user using the Botpress client by calling the `client.createUser()` method.
  </Step>

  <Step title="Create an external user">
    Create an <DefinitionReference /> on the <DefinitionReference /> using the <DefinitionReference />'s API or SDK.
  </Step>

  <Step title="Map the external user to the Botpress user">
    Update the <DefinitionReference /> on the <DefinitionReference /> to map it to the Botpress user. Please refer to the <DefinitionReference />'s documentation to know how to set extra metadata for the <DefinitionReference />. The <DefinitionReference /> must be able at any time to query the <DefinitionReference /> in order to retrieve the Botpress user ID from the <DefinitionReference />.
  </Step>

  <Step title="Map the Botpress user to the external user">
    Update the Botpress user to map it to the <DefinitionReference />. This is typically done by setting a tag on the Botpress user with the <DefinitionReference />'s ID.
  </Step>

  <Step title="Yield control back to the plugin">
    Yield control back to the plugin by returning an object containing the Botpress user's ID.
  </Step>
</Steps>

As reference, here's how this logic is implemented in the Zendesk integration:

```typescript src/index.ts {4,15,19,25,29,33,35} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  actions: {
    async createUser({ ctx, input, client }) {
      // Create a Botpress user:
      const { name, email, pictureUrl } = input
      const { user } = await client.createUser({
        name,
        pictureUrl,
        tags: {
          email,
          role: 'end-user',
        },
      })

      // Create an external user on Zendesk:
      const zendeskClient = getZendeskClient(ctx.configuration)
      const zendeskUser = await zendeskClient.createOrUpdateUser({
        role: 'end-user',
        external_id: user.id, // <= map to the Botpress user ID
        name,
        email,
        remote_photo_url: pictureUrl,
      })

      // Map the Botpress user to the external user:
      await client.updateUser({
        id: user.id,
        tags: {
          id: zendeskUser.id.toString(), // <= map to the external user ID
        },
      })

      // Yield control back to the plugin and return the user ID:
      return {
        userId: user.id, // <= return the Botpress user ID
      }
    },
  },
})
```

#### Implementing `startHitl`

The `startHitl` action is used by the <DefinitionReference /> to request the creation of a <DefinitionReference /> (typically a *ticket*) in the <DefinitionReference />.

<Note>
  If you opted to rename the action to something else than `startHitl` in the "Configuring the interface" section, please use the new name instead of `startHitl`.
</Note>

Please refer to the expected input and output schemas for the action:
[interface.definition.ts line 109](https://github.com/botpress/botpress/blob/023d7de196e63f1a1b7cac0cf4f97c3d4aac940f/interfaces/hitl/interface.definition.ts#L109).

This action should implement the following logic:

<Steps>
  <Step title="Fetch the Botpress user">
    Fetch the Botpress user with ID `input.userId` that was passed in the input parameters.
  </Step>

  <Step title="Retrieve the external user's ID">
    From the Botpress user's tags, retrieve the <DefinitionReference />'s ID.
  </Step>

  <Step title="Create a Botpress conversation">
    Create a Botpress conversation using the Botpress client by calling the `client.getOrCreateConversation()` method.
  </Step>

  <Step title="Create the HITL session">
    On the <DefinitionReference />, create the <DefinitionReference />. This is typically represented as a *ticket* in the <DefinitionReference />.
  </Step>

  <Step title="Map the Botpress conversation to the HITL session">
    Update the Botpress conversation to map it to the <DefinitionReference />. This is typically achieved by setting a `ticketId` tag on the Botpress conversation.
  </Step>

  <Step title="Map the HITL session to the Botpress conversation">
    Update the <DefinitionReference /> on the <DefinitionReference /> to map it to the Botpress conversation. Please refer to the <DefinitionReference />'s documentation to know how to set extra metadata for the <DefinitionReference /> (typically a *ticket*). The <DefinitionReference /> must be able at any time to query the <DefinitionReference /> in order to retrieve the Botpress conversation ID from the <DefinitionReference />.
  </Step>

  <Step title="Yield control back to the plugin">
    Yield control back to the plugin by returning an object containing the Botpress conversation's ID.
  </Step>
</Steps>

As reference, here's how this logic is implemented in the Zendesk integration:

```typescript src/index.ts {4,9,17,24,27,31,35,37,40,42} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  actions: {
    async startHitl({ ctx, input, client }) {
      // Fetch the Botpress user that was passed in the input parameters:
      const { user } = await client.getUser({
        id: input.userId,
      })

      // From the user's tags, retrieve the external user's id:
      const zendeskAuthorId = user.tags.id
      if (!zendeskAuthorId) {
        throw new sdk.RuntimeError(
          `User ${user.id} isn't linked to a Zendesk user`
        )
      }

      // Create a new ticket on Zendesk:
      const zendeskClient = getZendeskClient(ctx.configuration)

      const ticketTitle = input.title ?? 'Untitled Ticket'
      const ticketBody = 'A user created a support ticket'
      const createdZendeskTicket = await zendeskClient
        .createTicket(ticketTitle, ticketBody, {
          id: zendeskAuthorId, // <= map the ticket to the external user ID
        })

      // Create a Botpress conversation and map it to the Zendesk ticket:
      const { conversation } = await client.getOrCreateConversation({
        channel: 'hitl',
        tags: {
          id: createdZendeskTicket.id.toString(), // <= map to the ticket ID
        },
      })

      // Map the Zendesk ticket to the Botpress conversation:
      await zendeskClient.updateTicket(createdZendeskTicket.id, {
        external_id: conversation.id, // <= map to the Botpress conversation ID
      })

      // Yield control back to the plugin and return the conversation ID:
      return {
        conversationId: conversation.id, // <= return the Botpress conversation ID
      }
    },
  },
})
```

#### Relaying the conversation history

The input parameters of the `startHitl` action contain a `messageHistory` parameter. This parameter contains the conversation history that should be relayed to the <DefinitionReference /> to provide the <DefinitionReference /> with context about the conversation. This parameter is an array of every message that was sent in the conversation prior to the <DefinitionReference /> being started.

<Expandable title="TypeScript schema for the messageHistory parameter">
  ```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  type MessageHistory = Array<
    | TextMessage
    | ImageMessage
    | AudioMessage
    | VideoMessage
    | FileMessage
    | LocationMessage
    | CarouselMessage
    | CardMessage
    | DropdownMessage
    | ChoiceMessage
    | BlocMessage
    | MarkdownMessage
  >;

  type Source =
    | {
        type: "user";
        userId: string;
      }
    | {
        type: "bot";
      };

  interface TextMessage {
    source: Source;
    type: "text";
    payload: {
      text: string;
    };
  }

  interface ImageMessage {
    source: Source;
    type: "image";
    payload: {
      imageUrl: string;
    };
  }

  interface AudioMessage {
    source: Source;
    type: "audio";
    payload: {
      audioUrl: string;
    };
  }

  interface VideoMessage {
    source: Source;
    type: "video";
    payload: {
      videoUrl: string;
    };
  }

  interface FileMessage {
    source: Source;
    type: "file";
    payload: {
      fileUrl: string;
      title?: string;
    };
  }

  interface LocationMessage {
    source: Source;
    type: "location";
    payload: {
      latitude: number;
      longitude: number;
      address?: string;
      title?: string;
    };
  }

  interface CarouselMessage {
    source: Source;
    type: "carousel";
    payload: {
      items: Array<{
        title: string;
        subtitle?: string;
        imageUrl?: string;
        actions: Array<{
          action: "postback" | "url" | "say";
          label: string;
          value: string;
        }>;
      }>;
    };
  }

  interface CardMessage {
    source: Source;
    type: "card";
    payload: {
      title: string;
      subtitle?: string;
      imageUrl?: string;
      actions: Array<{
        action: "postback" | "url" | "say";
        label: string;
        value: string;
      }>;
    };
  }

  interface DropdownMessage {
    source: Source;
    type: "dropdown";
    payload: {
      text: string;
      options: Array<{
        label: string;
        value: string;
      }>;
    };
  }

  interface ChoiceMessage {
    source: Source;
    type: "choice";
    payload: {
      text: string;
      options: Array<{
        label: string;
        value: string;
      }>;
    };
  }

  interface BlocMessage {
    source: Source;
    type: "bloc";
    payload: {
      items: Array<
        | BlocTextItem
        | BlocMarkdownItem
        | BlocImageItem
        | BlocAudioItem
        | BlocVideoItem
        | BlocFileItem
        | BlocLocationItem
      >;
    };
  }

  interface BlocTextItem {
    type: "text";
    payload: {
      text: string;
    };
  }

  interface BlocMarkdownItem {
    type: "markdown";
    payload: {
      markdown: string;
    };
  }

  interface BlocImageItem {
    type: "image";
    payload: {
      imageUrl: string;
    };
  }

  interface BlocAudioItem {
    type: "audio";
    payload: {
      audioUrl: string;
    };
  }

  interface BlocVideoItem {
    type: "video";
    payload: {
      videoUrl: string;
    };
  }

  interface BlocFileItem {
    type: "file";
    payload: {
      fileUrl: string;
      title?: string;
    };
  }

  interface BlocLocationItem {
    type: "location";
    payload: {
      latitude: number;
      longitude: number;
      address?: string;
      title?: string;
    };
  }

  interface MarkdownMessage {
    source: Source;
    type: "markdown";
    payload: {
      markdown: string;
    };
  }
  ```
</Expandable>

If you decide to relay the conversation history to the <DefinitionReference />, you can do so by iterating over the `messageHistory` array and sending each message to the <DefinitionReference /> using its API or SDK. However, doing so might cause a significant number of notifications being sent to the <DefinitionReference />. To alleviate this, you can choose to send only the last few messages in the conversation history, or to concatenate the messages into a single message. For example you could combine messages like this:

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## User1 said:
> Hello, I need help with my order.

## Bot replied:
> I have escalated this conversation to a human agent. Please wait while I connect you.
```

#### Adding extra parameters to the `startHitl` action

If the <DefinitionReference /> requires extra parameters when starting a <DefinitionReference />, you can add them to the `hitlSession` entity, or whichever name you chose for the entity in the [Adding the interface to your integration definition file](#adding-the-interface-to-your-integration-definition-file) section. For example, if the <DefinitionReference /> requires a `priority` parameter, you can add it like this:

```typescript integration.definition.ts {5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new sdk.IntegrationDefinition({
  entities: {
    ticket: {                     // <= name of your entity
      schema: sdk.z.object({
        priority: sdk.z.string().optional(), // <= add the extra parameter here
      })
    },
  },
})
```

Doing so will display the `priority` parameter in the "Start HITL" card within the Botpress Studio, allowing the bot authors to set it. The value of this parameter will then be passed to the `startHitl` action as part of the `hitlSession` input parameter:

```typescript src/index.ts {5,10} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  actions: {
    async startHitl({ ctx, input, client }) {
      // Retrieve the extra parameter:
      const priority = input.hitlSession?.priority ?? 'normal'

      // Then use it to create the HITL session:
      const createdZendeskTicket = await zendeskClient
        .createTicket(ticketTitle, ticketBody, {
          priority, // <= pass the extra parameter to the external service
        })
    },
  },
})
```

#### Implementing `stopHitl`

The `stopHitl` action is used by the <DefinitionReference /> to request the closure of a <DefinitionReference /> (typically a *ticket*) in the <DefinitionReference />.

<Note>
  If you opted to rename the action to something else than `stopHitl` in the "Configuring the interface" section, please use the new name instead of `stopHitl`.
</Note>

Please refer to the expected input and output schemas for the action:
[interface.definition.ts line 162](https://github.com/botpress/botpress/blob/023d7de196e63f1a1b7cac0cf4f97c3d4aac940f/interfaces/hitl/interface.definition.ts#L162).

This action should implement the following logic:

<Steps>
  <Step title="Fetch the Botpress conversation">
    Fetch the Botpress conversation with ID `input.conversationId` that was passed in the input parameters.
  </Step>

  <Step title="Retrieve the HITL session's ID">
    From the Botpress conversation's tags, retrieve the <DefinitionReference />'s ID.
  </Step>

  <Step title="Close the HITL session">
    On the <DefinitionReference />, close the <DefinitionReference />. This is typically involves *resolving* or *closing* a *ticket* in the <DefinitionReference />.
  </Step>

  <Step title="Yield control back to the plugin">
    Yield control back to the plugin by returning an empty object.
  </Step>
</Steps>

<Note>
  The input parameters contain an unused `reason` parameter. Please ignore it. This parameter will be removed in future versions of the <DefinitionReference />.
</Note>

As reference, here's how this logic is implemented in the Zendesk integration:

```typescript src/index.ts {4,9,17,22} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  actions: {
    async stopHitl({ ctx, input, client }) {
      // Fetch the Botpress conversation that was passed in the input parameters:
      const { conversation } = await client.getConversation({
        id: input.conversationId,
      })

      // From the conversation's tags, retrieve the Zendesk ticket's id:
      const ticketId: string | undefined = conversation.tags.id
      if (!ticketId) {
        return {}
      }

      const zendeskClient = getZendeskClient(ctx.configuration)

      // Close the ticket on Zendesk:
      await zendeskClient.updateTicket(ticketId, {
        status: 'closed',
      })

      // Yield control back to the plugin:
      return {}
    },
  },
})
```

### Implementing the channel

The `hitl` channel is used by the <DefinitionReference /> relay <DefinitionReference /> messages to the <DefinitionReference />, which is usually a *ticket* or *thread* in the <DefinitionReference />.

<Note>
  If you opted to rename the channel to something else than `hitl` in the "Configuring the interface" section, please use the new name instead of `hitl`.
</Note>

This channel handler should implement the following logic:

<Steps>
  <Step title="Retrieve the HITL session's ID">
    From the Botpress conversation's tags, retrieve the <DefinitionReference />'s ID.
  </Step>

  <Step title="Retrieve the external user's ID">
    * If the payload contains a `userId` parameter, the message has been sent by the <DefinitionReference />. Retrieve the <DefinitionReference />'s ID from the tags of the Botpress user `payload.userId`.
    * If the payload doesn't contain a `userId` parameter, the message has been sent by the bot. Retrieve the <DefinitionReference />'s ID from the tags of the attached Botpress user.
  </Step>

  <Step title="Send the message to the HITL session">
    Using the <DefinitionReference />'s API or SDK, send the message to the <DefinitionReference />. This is typically a *comment* in a *ticket*.
  </Step>
</Steps>

As reference, here's how this logic is implemented in the Zendesk integration:

```typescript src/index.ts {6,9,17} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export default new bp.Integration({
  channels: {
    hitl: {
      messages: {
        async text({ client, conversation, ctx, payload, user }) {
          // Retrieve the ticket id from the conversation's tags:
          const zendeskTicketId = conversation.tags.id

          // Retrieve the external user:
          let zendeskAuthorId = user.tags.id

          if (payload.userId) {
            const { user: botpressUser } = await client.getUser({ id: payload.userId })
            zendeskAuthorId = botpressUser.tags.id
          }

          // Send the message to Zendesk:
          return await getZendeskClient(ctx.configuration)
            .createComment(zendeskTicketId, zendeskAuthorId, payload.text)
        },
      },
    },
  }
})
```

### Implementing the events

You should set up webhooks so that the <DefinitionReference /> receives notifications about these events:

* A new message is added to the <DefinitionReference /> (usually a *ticket*).
* A <DefinitionReference /> has been assigned to the <DefinitionReference />.
* The <DefinitionReference /> was closed.

#### Incoming messages

When notified by the <DefinitionReference /> that a new message has been added to the <DefinitionReference />, you should relay the message to the Botpress conversation:

<Steps>
  <Step title="Retrieve the Botpress conversation's ID">
    Retrieve the Botpress conversation's ID from the <DefinitionReference />'s metadata.
  </Step>

  <Step title="Retrieve the external user's ID">
    Retrieve the <DefinitionReference />'s ID from the <DefinitionReference />'s metadata.
  </Step>

  <Step title="Add a message to the Botpress conversation">
    Using the Botpress client, add a message to the Botpress conversation by calling the `client.createMessage()` method.
  </Step>
</Steps>

#### Implementing `hitlAssigned`

When notified by the <DefinitionReference /> that a <DefinitionReference /> has been assigned to the <DefinitionReference />, you should notify the <DefinitionReference /> by emitting the `hitlAssigned` event:

<Steps>
  <Step title="Retrieve the Botpress conversation's ID">
    Retrieve the Botpress conversation's ID from the <DefinitionReference />'s metadata.
  </Step>

  <Step title="Retrieve the external user's ID">
    Retrieve the <DefinitionReference />'s ID from the <DefinitionReference />'s metadata.
  </Step>

  <Step title="Emit the hitlAssigned event">
    Using the Botpress client, emit the `hitlAssigned` event by calling the `client.createEvent()` method.
  </Step>
</Steps>

<Note>
  If you opted to rename the event to something else than `hitlAssigned` in the "Configuring the interface" section, please use the new name instead of `hitlAssigned`.
</Note>

#### Implementing `hitlStopped`

When notified by the <DefinitionReference /> that the <DefinitionReference /> was closed, you should notify the <DefinitionReference /> by emitting the `hitlStopped` event:

<Steps>
  <Step title="Retrieve the Botpress conversation's ID">
    Retrieve the Botpress conversation's ID from the <DefinitionReference />'s metadata.
  </Step>

  <Step title="Retrieve the external user's ID">
    Retrieve the <DefinitionReference />'s ID from the <DefinitionReference />'s metadata.
  </Step>

  <Step title="Emit the hitlStopped event">
    Using the Botpress client, emit the `hitlStopped` event by calling the `client.createEvent()` method.
  </Step>
</Steps>

<Note>
  If you opted to rename the event to something else than `hitlStopped` in the "Configuring the interface" section, please use the new name instead of `hitlStopped`.
</Note>


# Introduction to interfaces
Source: https://botpress.com/docs/integrations/sdk/interface/introduction



## Overview

Interfaces in the Botpress SDK establish standardized contracts that integrations must implement to enable extra features and capabilities. For example, an integration might implement the `hitl` (human-in-the-loop) interface to support human agent intervention, or the `typing-indicator` interface to use typing indicators provided by the external service.

<Warning>Interface creation is **currently restricted to the Botpress Team**. Support for developer-created interfaces *may* be introduced in future releases at Botpress's sole discretion.</Warning>

## Interface Definition

Each interface is defined through an Interface Definition that specifies the contract integrations must fulfill.

## Key Components of Interface Definitions

### Events

Interfaces can define events that integrations must support. These events establish a consistent model for how activities are communicated to bots, regardless of the underlying external service.

### Actions

Interfaces can specify actions that integrations must provide. These actions define standardized operations that bots can invoke across different integrations that implement the same interface.

### Channels

Interfaces can define communication channel requirements that integrations must implement.

### Entities

Entities define standardized data structures for an interface. They:

* Establish common data models across different integrations
* Allow integrations to extend and customize the base entity

Actions and events defined by an interface may consume or produce these entities.

## Component Renaming

<Tip>
  Integrations can rename an interface's events, actions, channels, and entities to better align with the concepts and terminology of their specific external service. Integrations can also extend entities with additional fields to accommodate the requirements of their external service.
</Tip>

## Benefits of Interfaces

Interfaces provide significant benefits to the Botpress ecosystem:

* **Consistency**: Bots can interact with many external services through a standardized approach
* **Reusability**: Plugins can build upon interfaces instead of individual integrations
* **Adaptability**: Integrations can fulfill interface requirements while maintaining the appropriate terminology for their external service
* **Extensibility**: New integrations can quickly provide established functionality by implementing existing interfaces


# Overview
Source: https://botpress.com/docs/integrations/sdk/overview



The Botpress SDK provides a robust and lightweight foundation for developing components within Botpress.

## Key components

The SDK facilitates the development of four primary component types:

1. [Integrations](#integrations)
2. [Interfaces](#interfaces)
3. [Bots](#bots)
4. [Plugins](#plugins)

These components work together to create a cohesive and extensible architecture.

### Integrations

Integrations connect bots to external services and platforms, enabling communication between your bots and the outside world. With integrations, your bots can:

* Establish communication with messaging platforms like Slack, WhatsApp, and Telegram
* Access and manipulate data from services like Dropbox, Google Drive, or custom APIs
* Perform operations on behalf of users in external systems
* Trigger events in your bots based on actions in external services

<Card title="Getting started" icon="play" href="/integrations/sdk/integration/getting-started">
  Create your first integration
</Card>

### Interfaces

Interfaces are contracts that define the expected behavior of integrations. They specify the events and actions that integrations must implement to support specific features or functionalities. This concept is similar to interfaces in many popular general purpose programming languages, such as Java, C#, and TypeScript.

Examples of interfaces in Botpress include:

* **Human-in-the-loop (HITL)**: Defines the events and actions an integration must implement to support human agent intervention
* **Typing Indicator**: Defines the events and actions an integration must implement to use typing indicators supported by the external service

<CardGroup>
  <Card title="Read more" icon="book" href="/integrations/sdk/interface/introduction">
    Learn more about interfaces
  </Card>

  <Card title="How-to" icon="graduation-cap" href="/integrations/sdk/interface/how-tos/implementing-hitl">
    Learn how to implement the HITL indicator interface
  </Card>
</CardGroup>

### Bots

The Botpress SDK allows developers to create bots using code instead of the Botpress Studio web interface. We refer to these bots as **bots-as-code**.

<Warning>
  We recommend using Botpress Studio for most use cases. Bots-as-code aren't intended to replace Studio and are best suited for experienced developers who need more flexibility or tighter integration with version control systems.
</Warning>

Bots-as-code are used internally by the Botpress team as well, since both the Studio and SDK share the same underlying primitives.

Just like bots built in Studio, bots-as-code can:

* Use multiple integrations to communicate across different platforms
* Define custom events, primarily for scheduling purposes (to trigger self-execution at specified times or intervals)
* Subscribe to events from integrations and interfaces to execute business logic

<Card title="Getting started" icon="play" href="/integrations/sdk/bots-as-code">
  Create your first bot-as-code
</Card>

### Plugins

Plugins are reusable pieces of bots; modular, reusable components that extend bot functionality. Like bots, they can listen to events and messages, define hook functions for different stages of the bot lifecycle, send messages, and more. The key difference is that plugins are designed to be shared and reused across multiple bots.

Currently, only the Botpress team can create plugins, similar to how interfaces are managed. While community-created plugins aren't supported yet, this may change in future releases. In the meantime, users can install official Botpress plugins directly from Studio—for example, the **HITL Plugin**, which enables your bot to work with integrations that implement the `hitl` interface.

## The HITL system

In Botpress, **HITL** (Human-in-the-Loop) may refer to an integration, an interface, or a plugin. The HITL system as a whole is a combination of these components working together to provide a human-in-the-loop experience.

The **HITL interface** defines the events and actions that an integration must implement to support human agent intervention. This interface is used by both the HITL plugin and the HITL integration.

The **HITL integration** is similar to integrations like Zendesk or Freshchat. It connects your bot to an external customer support service and implements the `hitl` interface by providing the required events and actions.

The **HITL plugin** contains the logic for human-in-the-loop functionality. It forwards messages to a human agent and allows the agent to respond. The plugin depends on the HITL interface, meaning it can work with any integration that implements it, including the HITL integration.

<CardGroup>
  <Card title="Read more" icon="book" href="/integrations/sdk/interface/how-tos/implementing-hitl">
    Learn how to implement the HITL interface in your integration
  </Card>
</CardGroup>

## Recommendations

The Botpress SDK leverages TypeScript's strong typing system. We strongly recommend using an IDE that offers strong IntelliSense for TypeScript such as [Visual Studio Code](https://code.visualstudio.com). When in doubt, the SDK types should be used as a reference for the expected types and structures of various components.


# Actions
Source: https://botpress.com/docs/studio/concepts/actions



<Icon icon="bolt" /> Actions are **custom AI-generated tools** you can provide to your bot.

<Tabs>
  <Tab title="Just write your prompt...">
    <Frame>
      <img alt="Action prompt" />

      <img alt="Action prompt" />
    </Frame>
  </Tab>

  <Tab title="then use the generated Action.">
    <Frame>
      <img alt="Generated action" />

      <img alt="Actions" />
    </Frame>
  </Tab>
</Tabs>

You can use Actions to extend your bot's general functionality beyond what's available with the default [Cards](/docs/studio/concepts/cards/introduction) or [integrations](/docs/integrations/get-started/introduction). For example:

* Make repeated API calls to an external service
* Perform a specific calculation multiple times
* Manipulate data and [variables](/docs/studio/concepts/variables/overview)

<Tip>
  Actions are code-based, but you don't need to write the code yourself—AI does all the work based on your prompt.
</Tip>

***

## Overview

Actions are [TypeScript functions](https://www.typescriptlang.org/docs/handbook/2/functions.html) that execute their code whenever an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) calls them.

Just like [Execute Code Cards](/docs/studio/concepts/cards/execute-code), Actions let your bot use custom code. However, they're different in two important ways:

* Actions are *only available in Autonomous Nodes*—they execute when AI decides they should
* Actions are *re-usable*—your Autonomous Node can call them as many times as it needs

***

## Create an Action

To create a new Action:

1. Go to the **<Icon icon="bolt" /> Actions** menu in the Studio.
2. Select **Create Action**.

This opens the editor for your new Action. From here, you have two options:

### Generate using AI (recommended)

You can generate the entire Action using AI. In the bottom-left corner, write a prompt that describes what you want your Action to do:

<Frame>
  <img alt="Action prompt example" />

  <img alt="Action prompt example" />
</Frame>

Your bot will generate code based on your prompt:

<Frame>
  <img alt="Generated Action code" />

  <img alt="Generated Action code" />
</Frame>

If you want to refine the code, you can keep prompting to make updates.

When you're happy with the generated code, select **Accept** to add it to your Action.

### Write code yourself

If you prefer, you can write the Action's code yourself—just edit the function on the right side of the editor.

<Note>
  For more information, check out our guide on [using code in Botpress Studio](/docs/studio/guides/advanced/use-code).
</Note>

### Edit your Action's name/description

Whether you generate your Action with AI or write it by hand, you can edit its name and description. Just select them in the upper-left corner of the editor, then enter a new name/description.

***

## Use Actions

When you're ready to use an Action, you can add it to any Autonomous Node:

1. Select **+ Add Card** on any Node to open the Card tray.
2. Search for your Action, or find it under **Bot Actions**.
3. Add it to the Autonomous Node.

This gives your Autonomous Node access to execute the Action whenever it decides it's appropriate.

### Give your Autonomous Node instructions

If you add an Action to your Autonomous Node, you should add instructions to the Node's prompt so it knows when to use the Action. For example:

```wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Use the `fetchApiData` Action when you need data from an external API.
```

For more information, check out our guide on prompting your [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node#prompting-tips).

### Manually provide inputs

By default, the Autonomous Node decides how to fill in the Action's input fields based on the conversation's context. However, you can manually fill in these fields if you'd prefer:

1. Select your Action from the Autonomous Node to open its inspector.
2. Select the input field you want to manually fill in, then select **<Icon icon="hand" /> Manual.**

Now, you can manually fill in the field. For example, with data stored in a variable:

<Frame>
  <img alt="Manually provide inputs" />

  <img alt="Manually provide inputs" />
</Frame>

***

## Schemas

Actions use input and output [Schemas](/docs/studio/concepts/schemas) to tell your bot what data they expect and what data to return.

Schemas are automatically created when you create an Action, and they automatically update when you edit your Action using AI. This means you don't have to worry about them if you're only using AI to generate your Action.

### Use custom Schemas

If you're writing any of your Action's code by hand, you can write or select a custom Schema:

1. In your Action's editor, select **<Icon icon="braces" /> Input Schema** or **<Icon icon="braces" /> Output Schema**.
2. Here, you can edit your Action's default Schema directly, or select a previously-created Schema from the drop-down menu.


# Analytics Agent
Source: https://botpress.com/docs/studio/concepts/agents/analytics-agent

Collects, analyzes, and stores data on bot interactions.

The Analytics Agent collects and analyzes data on bot interactions to provide insights into user behaviour, bot performance, and conversation trends. This agent is crucial for monitoring and improving the bot’s effectiveness.

## Configuration

<Note>
  Note

  The Analytics Agent is only available to Team and Enterprise subscribers.
</Note>

Once you've enabled the Analytics Agent from your bot's Agents menu, you can designate custom events that your bot will track. These events can be selected from the list of trackable events, or "Event Types."

### Tracking custom events

Follow these steps to track custom events:

1. Place the "Track Event" card found in the "Agents" section of the card tray into a node
2. In the details panel, use a descriptive name for the event that will allow you to keep track of it later. For example, you might track "Successful resolution" or "Unanswered question."

Once you've successfully created a custom event, your bot will track each event as the card is executed in a given node. For example, your bot can track how many times a conversation successfully reaches a specific node, or how often users go through a certain node.

<Warning>
  Warning

  After creating a custom event, it can take up to an hour before the data is available to be visualized in your Analytics tab.
</Warning>


# HITL Agent
Source: https://botpress.com/docs/studio/concepts/agents/hitl-agent

Allows human intervention in the bot's conversations and decision-making.

<Warning>
  The Human-in-the-loop (HITL) Agent is **deprecated** and is no longer available to new accounts. Please use the [HITL Plugin](/docs/integrations/integration-guides/hitl/introduction) instead.

  If you have a HITL Agent enabled, it will remain available for the time being. However, if you disable the Agent, you won't be able to restore it.
</Warning>

The HITL (Human-in-the-Loop) Agent allows human intervention in the bot’s conversations and decision-making. This is particularly useful in complex scenarios where the bot might need confirmation or input from a human operator.

## Configuration

### Escalation Integration

This is the integration you will use to handle the escalation.

You can enable HITL with a prebuilt integration, or build a custom integration if you're using a third-party customer support provider that isn't listed here:

| Integrations that support HITL |
| :----------------------------- |
| Zendesk                        |
| HITL (Botpress)                |

### Queue Timeout

This is the maximum wait time the bot will wait for an agent to handle the user's query. This time is set in minutes. If this timeout limit is reached, the bot will continue on with the current Workflow.

### Intent to cancel HITL

This option allows the user to cancel their request to speak to a human agent.

The intents can be created and configured through the Library in the Studio.

### Transcript Context

This is what the bot will send to the human agent as additional context for the user's request. The default information includes the channel and integration on which the user was having the conversation, as well as both the Summary and Transcript variables generated by the Summary Agent.

You can customize this to include whatever pieces of information are necessary for your specific scenario. This field supports variable expressions.

### HITL Messages

In these sections, you can customize what message your bot sends in various steps of the HITL process. These include:

* while the end user is waiting to speak to an agent
* when an agent is assigned to an end user
* when the human agent ends the interaction
* when the end user cancels the request
* when the agent request times out

## Exposed Variables

The HITL Agent exposes three variables for use:

```
{{conversation.HITLAgent.isHitl}}
```

```
{{conversation.HITLAgent.hitlSessionStatus}}
```

```
{{conversation.HITLAgent.hitlContext}}
```


# Agents
Source: https://botpress.com/docs/studio/concepts/agents/introduction

Specialized components that extend the capabilities of a bot.

<Icon icon="bot" /> Agents **extend your bot's capabilities** beyond its basic functions. They perform tasks that enhance your bot's interactions with users, like:

* [Enforcing policies](/docs/studio/concepts/agents/policy-agent) across your bot's interactions
* Allowing your bot to [communicate in multiple languages](/docs/studio/concepts/agents/translator-agent)
* Providing [summaries and transcripts](/docs/studio/concepts/agents/summary-agent) of your bot's conversations

## Guides

Select any Agent to learn more about it:

<CardGroup>
  <Card title="Summary Agent" href="/studio/concepts/agents/summary-agent">
    Condenses the conversation into an AI-generated summary and transcript
  </Card>

  <Card title="Personality Agent" href="/studio/concepts/agents/personality-agent">
    Provides your bot with a personality or tone
  </Card>

  <Card title="Policy Agent" href="/studio/concepts/agents/policy-agent">
    Enforces business rules and compliance guidelines across your bot's interactions
  </Card>

  <Card title="Translator Agent" href="/studio/concepts/agents/translator-agent">
    Allows your bot to communicate in multiple languages
  </Card>

  <Card title="Knowledge Agent" href="/studio/concepts/agents/knowledge-agent">
    Retrieves information from the bot's knowledge base
  </Card>

  <Card title="Analytics Agent" href="/studio/concepts/agents/analytics-agent">
    Collects, analyzes, and stores data on bot interactions
  </Card>

  <Card title="Vision Agent" href="/studio/concepts/agents/vision-agent">
    Adds image recognition and visual processing capabilities to your bot
  </Card>

  <Card title="HITL Agent" href="/studio/concepts/agents/hitl-agent">
    Allows human intervention in the bot's conversations and decision-making
  </Card>
</CardGroup>

## Order of execution

When your bot has multiple Agents enabled, they execute in the following order:

1. Summary
2. Personality
3. Policy
4. Translator
5. Knowledge
6. Vision
7. Router
8. Analytics
9. HITL Agent


# Knowledge Agent
Source: https://botpress.com/docs/studio/concepts/agents/knowledge-agent

Retrieves information from the bot's knowledge base.

The Knowledge Agent is responsible for retrieving information from the bot’s knowledge bases, such as FAQs, documents, websites, or structured databases. This agent is essential for providing accurate and detailed answers to user queries.

## Configuration

### Answer Manually

When this option is enabled, your bot won't automatically provide answers in the conversation. The answers it generates will be saved to a dedicated variable which you can use manually in the conversation at a later point.

### Additional Context

This setting enables the bot to include extra contextual information when generating answers. By considering additional context, the Knowledge Agent can provide more accurate and relevant responses, especially in complex or nuanced scenarios.

### Model Strategy

The "Model Strategy" option allows you to choose how the Knowledge Agent selects and applies machine learning models to generate answers. Depending on your strategy, the agent can prioritize different models based on speed, accuracy, or specific use cases.

**Fastest Model**: This is the model you designate as being the fastest, suited to your specific need. Generally, these are considered quicker, more performant, and less expensive models, and should be used when you anticipate simple queries.

**Best Model**: This is the model you designate as being the most performant, suited to your specific need. Generally, this option should be used only when you anticipate that the additional performance of a more expensive model will be needed

**Question Extractor Model**: This is the model used to extract questions from a conversation. Generally, you should follow the above rules here: a faster model if you anticipate simple queries, and a more performant one if the questions you expect to receive will be complex.

### Chunks Count

This is the number of chunks that Botpress will elect to send from the Knowledge Base to a model to generate an answer. A larger number of chunks will send more information to the model, generally resulting in more accurate answers, with longer generation times and a higher token cost.

## Exposed Variables

The Knowledge Agent exposes two variables that you can use:

### Generated Response

```
{{turn.KnowledgeAgent.answer}}
```

### Response citations

```
{{turn.KnowledgeAgent.citations}}
```


# Personality Agent
Source: https://botpress.com/docs/studio/concepts/agents/personality-agent

Provides your bot with a personality or tone.

The Personality Agent is used to provide the bot with a personality or tone. This agent controls how the bot expresses itself, including its language style, tone, and the types of responses it generates.

## Configuration

### Enable Personality Rewriting

When this option is enabled, all of the messages your bot sends to end users will be rewritten to match the personality you indicate.

### Personality Description

The description you use here will be used along with an LLM to define and rewrite the messages your bot sends to end users. Think of this like the prompt you would send to an LLM to generate a certain type of response. You can include information about personality, tone, and purpose.

This field also supports variable expressions. For example, you can use a predefined variable to dynamically change the name of the bot based on information you collect at the beginning of a conversation.

### Model

This is the model your bot will use to rewrite the responses it generates to suit the personality you've indicated in the Personality Description section.


# Policy Agent
Source: https://botpress.com/docs/studio/concepts/agents/policy-agent

Enforces business rules and compliance guidelines across your bot's interactions.

The Policy Agent is designed to enforce business rules, compliance guidelines, or specific operational policies during bot interactions. It ensures that the bot adheres to legal, regulatory, or company-specific policies that you designate.

## Configuration

### Policy Description

In this field, you can describe the policies to which you want your bot to adhere.

If there are certain off-brand words that your bot should stay away from when generating responses, or you'd like your bot to avoid providing information about competitors' products or services, you can indicate that here.

### Model

This is the model used to influence and generate responses in accordance with the Policy Description.

### Additional Information

The Policy Agent is a powerful tool that enhances the safety and control of LLM-driven interactions by enforcing constraints and managing compliance across your bot's conversations. As organizations increasingly adopt AI-driven solutions, maintaining control over these systems is paramount. The Policy Agent acts as a safeguard, ensuring that all bot interactions remain within the defined boundaries of your business rules, regulatory standards, and operational policies. This not only helps protect your brand but also instills confidence in your organization's use of AI technology.

One of the critical challenges with LLMs  is the risk of generating responses that may be off-brand, inaccurate, or non-compliant—often referred to as "hallucinations." These hallucinations can lead to misleading or incorrect information being provided to users. The Policy Agent directly addresses this risk by functioning as a gatekeeper, filtering and controlling the responses generated by your AI. By configuring specific constraints, such as banned words, sensitive topics, or off-limits information, the Policy Agent ensures that the output remains aligned with your organization’s guidelines, protecting both your reputation and legal standing.

The Policy Agent also introduces control mechanisms that act as gates for bot behaviour. These gates serve as checkpoints, ensuring that every interaction complies with designated business rules before it reaches the end user. This control extends to the specific contexts in which your AI operates, allowing it to adapt to various business needs while maintaining stringent adherence to predefined policies. Whether it's preventing the bot from discussing competitor products or controlling language to avoid sensitive terms, the Policy Agent’s gates provide a reliable framework to keep LLMs operating safely within set parameters.

By integrating constraints directly into the model, the Policy Agent not only enhances compliance but also minimizes the likelihood of unwanted behaviours. These constraints act as a foundational control layer, enabling decision-makers to trust that Botpress bots will behave predictably and within the bounds of their company’s standards. The end result is a robust, reliable system that not only enhances the operational capabilities of your bots but also significantly reduces the risk of regulatory non-compliance and brand-damaging missteps.

The Policy Agent provides a comprehensive solution for controlling LLM-driven interactions, ensuring that your organization’s use of AI remains safe, compliant, and within the bounds of designated rules. By implementing constraints, gates, and robust control measures, it acts as a critical safeguard, making it an essential tool for any business aiming to leverage AI while maintaining strict adherence to its policies.


# Summary Agent
Source: https://botpress.com/docs/studio/concepts/agents/summary-agent

Condenses the conversation into an AI-generated summary and transcript.

The Summary Agent condenses lengthy or complex pieces of information gathered throughout a conversation into shorter, digestible summaries. This is particularly useful in scenarios where you need a quick understanding of a conversation or interaction's context without going through all the details.

## Configuration

### Summary Max Tokens

This is the maximum length of the AI-generated summary, measured in tokens.

### Transcript Max Lines

This is the maximum length of the conversation transcript that the agent will record to the Conversation Transcript variable.

### Model

This is the model used to generate the summary that can be accessed through the Conversation Summary variable.

## Exposed Variables

The Summary Agent exposes two variables:

### Conversation Summary

```
{{conversation.SummaryAgent.summary}}
```

The Conversation Summary variable stores an AI-generated summary of the conversation up to the point at which it's accessed.

### Conversation Transcript

```
{{conversation.SummaryAgent.transcript}}
```

The Conversation Transcript variable stores an exact transcript of the conversation up to the point at which it's accessed.


# Translator Agent
Source: https://botpress.com/docs/studio/concepts/agents/translator-agent

Enables your bot to communicate in multiple languages.

The Translator Agent enables the bot to communicate in multiple languages by automatically translating text between different languages. This agent is crucial for bots that need to operate in a multilingual environment.

## Configuration

### Detect Initial User Language

When this option is enabled, the agent will automatically detect the language in which the user is communicating on the first incoming message it receives.

The message must be at least 3 tokens in order to be processed by the agent. Note that this process will automatically overwrite the language variable, even if you set that variable manually at the beginning of the conversation.

### Detect Language Change

When this option is enabled, the agent will attempt to detect the user's language on ever conversation turn. This is particularly useful if you expect the user's language to switch throughout a single conversation.

If this option is disabled, the agent will only detect the user's language when it's designated as 'null'.

### Model

This is the model your agent will use to translate messages.

## Exposed Variables

The Translator Agent exposes one variable for use:

```
{{user.TranslatorAgent.language}}
```


# Vision Agent
Source: https://botpress.com/docs/studio/concepts/agents/vision-agent

Adds image recognition and visual processing capabilities to your bot.

The Vision Agent adds image recognition and visual processing capabilities to the bot. It allows the bot to analyze and interpret visual data, such as images, screenshots, or camera feeds.

<Info>
  To use the Vision Agent, you need to:

  * Add the **Extract Content from Image** Card to your Autonomous Node
  * Enable **Extract from Incoming Images** in your [Autonomous Node's configuration](/docs/studio/concepts/nodes/autonomous-node#configuration)
</Info>

## Configuration

### Extract from Incoming Images

When this option is enabled, the bot will attempt to extract any text content from an image. It will also produce a description of the image itself.

The Vision Agent will save any extracted content and descriptions to the variable it exposes.

### Exposed Variables

The Vision Agent exposes one variable for use:

```
{{turn.Visionagent.content}}
```


# Bot Settings
Source: https://botpress.com/docs/studio/concepts/bot-settings



The **<Icon icon="settings" /> Bot Settings** menu lets you adjust general settings that apply to your bot.

## General options

### Bot name

Use this field to set a name for your bot. This name will display to users, regardless of which channel your bot is deployed on.

## Workflow options

### Inactivity timeout

This is the amount of time, in minutes, that your bot will wait for a response before ending the session. When the session ends, your bot will automatically trigger the [Timeout Workflow](/docs/studio/concepts/workflows#timeout). This clears the user's position in the Workflow and resets any Workflow variables.

You can set this to 0 to prevent the bot from ever timing out. The maximum value is 1440 minutes, or 24 hours.

### Node repetition limit

This is the maximum amount of times a conversation can go through any specific Node. When the user reaches this node repetition limit, an error will be triggered.

The maximum value is 10.

### Use the Botpress Client

This option lets you access the [official Botpress client for TypeScript](https://www.npmjs.com/package/@botpress/client) within Studio.

When enabled, the `client` object is imported by default anywhere you can [use code in Studio](/docs/studio/guides/advanced/use-code).

### Configuration variables

Here, you can [define and manage configuration variables](/docs/studio/concepts/variables/scopes/configuration) for your bot.

## LLM options

In this section, you can configure which Large Language Model (LLM) your bot's [Autonomous Nodes](/docs/studio/concepts/nodes/autonomous-node) should use depending on its current task.

<Tip>
  You can [override these settings](/docs/studio/concepts/nodes/autonomous-node#override-default-models) for individual Autonomous Nodes.
</Tip>

### Default fast LLM

This is the model your bot will use for quick and easy tasks, prioritizing speed and cost over performance.

### Default best LLM

This is the model your bot will use for complex tasks that need the highest-quality responses.

### Autonomous language model

This is the model that powers your bot's inference engine and generates responses.

### RAG language model

This is the model your bot will use for Retrieval-Augmented Generation (RAG) tasks, like answering questions based on [Knowledge Base](/docs/studio/concepts/knowledge-base/introduction) content.

### Fallback LLM

This is the model your bot will use when one of your preferred models is unavailable.

### LLMz version

This option lets you configure which version of Botpress' custom inference engine, LLMz, your bot uses.

<Warning>
  We recommend always using latest stable version of LLMz. However, you may find that a bot built on previous versions of LLMz works best on those versions.
</Warning>


# Hub
Source: https://botpress.com/docs/studio/concepts/card-hub

Download and install integrations with external services or premade Workflows from across the web.

From the Hub, you can download and install prebuilt Workflows or integrations for use within your bots. The Hub is designed to save time and enhance your development by providing access to Workflows and integrations created by Botpress, your team, or other <Tooltip>bot builders</Tooltip> in the community.

Cards and integrations are accessible through the Hub, a centralized library where you can browse and select assets to add directly to your projects. Whether you're integrating common functions like user authentication, setting up a third-party service like a CRM or analytics provider, or implementing complex interactions like a multi-step booking Workflow, the Hub makes it easy to find and deploy what you need.

## Accessing the Hub

The Hub is accessible from the top of the Studio, represented by an icon shaped like a globe.

## Installation and use

Use the search bar to look for specific functions, like 'message delay' or 'NPS survey,' or integrations with external services like 'HubSpot'.

When you've found a Workflow or integration you want to install, click on the 'Install' button.

* Workflows will be added for use to your card tray
* Integrations will usually make a set of cards available in a dedicated section of your card tray.

Both Workflows and integrations usually require some configuration before they can be used.

You can use a card by dragging it from the tray into a node. When the Workflow reaches this card, your bot will execute the prebuilt Workflow, along with any options you were prompted to configure during installation.

For integrations, follow the prompts to configure the service as needed.

## Customizing a Workflow

Right-clicking on a Workflow card once you've added it to your Workflow, or revisiting the installation menu from the Hub, allows you to make a copy of the Card and modify its contents.

This creates a version of the installed Card available as a Workflow directly in your bot, enabling you to make any custom changes needed.

These changes won't affect the public listing of the Workflow.

## Sharing Workflows

To share your own Workflow as a card available on the Hub, follow these steps:

1. Navigate to the Workflow you'd like to share.
2. On the right-side panel, click 'Share Workflow.'
3. Follow the steps in this menu to make the Card public.


# Agents
Source: https://botpress.com/docs/studio/concepts/cards/agents

Cards that interact with specific Agent functionalities.

The cards in the Agents category allow you to perform actions that integrate with your agent's functionalities in some way.

## Knowledge Agent

The Query Knowledge Bases card allows you to programmatically query Knowledge Bases from within your bot. This card is useful when you want to retrieve information from your Knowledge Bases and display it to the user during the conversation.

This supports variables and expressions. and won't send the answer directly to the user.

### Query

The question you want to ask to the Knowledge Base. You can type the question directly or use variables. for example: `{{event.preview}}` or `{{workflow.question}}`

### Included Knowledge Bases

Select in which Knowledge Bases to answer questions from. By default, it uses all the Knowledge Bases.

The result will be stored in `{{turn.KnowledgeAgent.answer}}` and `{{turn.KnowledgeAgent.citations}}`. You can also store the answer in Workflow variables.


# AI Generate Text
Source: https://botpress.com/docs/studio/concepts/cards/ai/ai-generate-text

A card that allows you to define a custom prompt to generate text.

The AI Generate Text card is a specific type of AI Task that helps you generate text based on a prompt and a few settings. This is useful for countless different use cases such as:

* Generating catchy blog titles from a topic or keyword
* Summarizing long texts or documents in a few sentences
* Creating articles from bullet points or outlines
* Writing product descriptions that highlight the features and benefits
* Crafting creative content such as stories, poems, lyrics, and more!

## Using AI Generate Text

You have a few settings in the AI Generate Text card:

* Prompt: the text you want to use as a starting point for the AI to generate content, you can use variables here (like `{{event.preview}}` to get the last user message)
* Output variable: the variable where the generated text will be stored
* Advanced settings > Model: the LLM model you want to use to generate the text (the current options are GPT-3 and GPT-4)
* Advanced settings > Temperature: the higher the temperature, the more creative the text will be
* Advanced settings > Output length: the length of the generated text in tokens. Check out [this article by OpenAI](https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them) to learn more about LLM tokens.

<Note>
  Note

  Use variables in the prompt to make the generated text more dynamic. For example, `{{event.preview}}` to get the last user message or `{{conversation.SummaryAgent.transcript}}` to get the history of the conversation and use it as a starting point for the AI.
</Note>


# AI Task
Source: https://botpress.com/docs/studio/concepts/cards/ai/ai-task

Perform specific and defined AI-powered actions in your bot's Workflow.

## AI Task Overview

The AI Task is a tool for generating content using AI and can be used to automate a wide range of tasks. By providing clear instructions, specific inputs, and well-named variables, users can leverage the full capabilities of this tool to improve their Workflows and boost their productivity.

### Task Instructions

To accomplish a generative task using the **AI Task Card**, users will need to provide specific instructions in natural language on what they want the AI engine to generate. This can be done using the **Task Instructions** parameter.

Users should provide a clear and detailed description of the task they want the AI engine to perform, including any relevant constraints or guidelines that should be followed.

There is a certain date beyond which the information isn't available to the AI model. You can find that date on the model you use (for example [GPT-3-5](https://platform.openai.com/docs/models/gpt-3-5) ). If you want to get around this, please use a Knowledge Base and add its answer as an input to give context to the AI Task.

### AI Task Input

This is the input that will be sent to the Generative AI Engine. Think of it as the problem subject. Users should be as specific as possible when providing the AI task input, as this will help the AI engine generate more accurate and relevant content. You can use multiple variants as an input - not limited to:

To make your AI task take into account the current date, you need to include it in the input by using this code snippet that shows the current date in JavaScript format: `Today's date: {{ new Date().toLocaleString() }}`

### Storing result in variables

This allows users to specify the variables where the extracted information will be stored within Botpress. It's important to choose variable names that are easy to understand and identify, as these variables will be used to reference the generated content in other parts of the Studio and it will influence the AI task on what to extract and how.

## Task Example

### Example Input

By providing clear and realistic examples, you can help the AI better understand its task and be used\\\
to solve real-world problems and generate useful content. This can ultimately lead to a more successful and productive experience for users who are targeting the power of artificial intelligence in their Workflows.

### Displaying result (optional)

You still need a content-type card to display the output of the AI Task Card if you want to.

## Advanced Settings

### Temperature

Temperature is a setting that controls how creative and varied the responses generated by an AI language model can be. Think of it like a dial that you can turn up or down to control how much the AI is allowed to come up with new and different responses. It ranges from 0 to 1.

When the temperature is set to 0, the AI will stick to the same answer most of the time, which can be useful for tasks that require consistency and accuracy. However, if you want more creative and varied responses, you can turn up the temperature, and the AI will come up with more diverse answers that may not always be the same.

For example, if you ask the LLM "What is your favorite animal?", with a temperature of 1 it might respond with "My favorite animal is a cat because they're cute and cuddly", but it might also generate a response like "My favorite animal is a platypus because they're such odd creatures and so unique". Both responses are consistent with the LLM's training data (which includes information about cats and platypuses), but the second response is more creative and unexpected.

In simpler terms, temperature is a way to control how much "imagination" the AI has when generating responses. A lower temperature means more consistency, while a higher temperature means more creativity and variability.

### Add transition to handle failure

You can enable this option to have your bot transition to another node when an issue happens with the AI Task. The possible issues are: Request Timeout (when the AI can't answer in a timely manner), Token Overflow (when the input or the output of the task exceeds the limit) and others.


# AI Transition
Source: https://botpress.com/docs/studio/concepts/cards/ai/ai-transition

Transition card that uses AI to determine a user's intent from a natural language input.

## AI Transition Overview

The AI Transition card is a specific type of AI Task that helps you classify text into a set of predefined categories. This is useful for several different cases such as assessing the user intent without needing to create training phrases, or extracting the main topic of a text.

## Using AI Transitions

You have three fields in the AI Transition card:

* Text to categorize: the text input you want to process, you can use variables here (like `{{event.preview}}` to get the last user message)
* Categories: the list of categories you want to use to classify the text.
* Store result in variable (Optional): allows you to select a variable to store the resulting category in. This is useful if you want to use the category later in the conversation.

<Info>
  Info

  You can use the AI Transition card to replace Intents. You just need to create a category for each intent you want to replace, and use the AI Transition card instead of adding multiple inline or Library intents.
</Info>


# AI
Source: https://botpress.com/docs/studio/concepts/cards/ai/introduction

These cards use AI by default to power their actions.

The cards in the AI section of the card tray are specialized tools that leverage advanced AI capabilities, including natural language processing, data analysis, and machine learning, to enhance your bot's functionality. These cards allow your bot to perform complex tasks, such as summarizing content, translating languages, analyzing user input, and more, adding intelligence and adaptability to your conversational Workflows.

<Tip>
  AI is everywhere!

  In addition to these dedicated, AI-powered cards, you'll find that LLMs power almost every aspect of the Botpress conversational experience.

  These cards provide you direct, task-based access to LLMs, giving you more control over their inputs and outputs.
</Tip>

There are three types of cards made available to you in the AI section of the card tray:

[AI Task](/docs/studio/concepts/cards/ai/ai-task)

[AI Transition](/docs/studio/concepts/cards/ai/ai-transition)

[AI Generate Text](/docs/studio/concepts/cards/ai/ai-generate-text)


# Capture Information
Source: https://botpress.com/docs/studio/concepts/cards/capture-information

Cards that stop the bot's Workflow and waits for a user's response to capture specific pieces of information.

**Capture Information** cards instruct the bot to stop processing and wait for the user's response while capturing a specific piece of information from the user's input.

This could include details like the user's name, full address, or raw input.

To collect multiple pieces of information, multiple prompt fields can be added to a single prompt node. Once the information is collected, a Workflow variable should be created to store the extracted information for later use in the conversation or to be passed on to other systems. This allows for a more personalized and efficient experience for the user, as well as providing valuable data for the bot's developers.

## Prompt Field Types

A Prompt Field is a type of input field that's used to capture information from a user in a structured and organized manner. It can include various types of input fields such as Single Choice, Multiple Choice, Number, Email Address, Phone Number, and more.

The Prompt Field also includes validation messages and code validation, which helps ensure that the user inputs the correct type of information. This means that if the user inputs an invalid value, they will be notified with an error message and prompted to re-enter the correct information.

<table>
  <thead>
    <tr>
      <th>
        **Prompt Fields**
      </th>

      <th>
        **Description & Extracted Information**
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        [SingleChoice](#single-choice)
      </td>

      <td>
        Extracts a Single Choice from a finite list of possible Values\
        Variable Type: String
      </td>
    </tr>

    <tr>
      <td>
        [MultipleChoice](#multi-choice)
      </td>

      <td>
        Extracts one or multiple choices from a finite list of possible Values\
        Variable Type: String
      </td>
    </tr>

    <tr>
      <td>
        [Boolean](#boolean)
      </td>

      <td>
        Extract a Boolean (On/Off) from the Query\
        Variable Type: Boolean
      </td>
    </tr>

    <tr>
      <td>
        [Confirmation](#confirmation)
      </td>

      <td>
        Confirm a Yes/No question with a Boolean from the Query\
        Variable Type: Boolean
      </td>
    </tr>

    <tr>
      <td>
        [Number](#number)
      </td>

      <td>
        Extracts a Number from the Query\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [EmailAddress](#email-address)
      </td>

      <td>
        Extracts a full Email Address from the Query\
        Variable Type: String
      </td>
    </tr>

    <tr>
      <td>
        [PhoneNumber](#phone-number)
      </td>

      <td>
        Extracts a Telephone Number and optionally the Country Code from the Query\
        Variable Type: String
      </td>
    </tr>

    <tr>
      <td>
        [FullAddress](#fulladdress)
      </td>

      <td>
        Extract the Full Address from the Query\
        Variable Type: Object
      </td>
    </tr>

    <tr>
      <td>
        [Price](#price)
      </td>

      <td>
        Extracts a Price from the Query\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [RawInput](#raw-input)
      </td>

      <td>
        Extract the Input provided by the User, without any processing\
        Variable Type: String
      </td>
    </tr>

    <tr>
      <td>
        [Percentage](#percentage)
      </td>

      <td>
        Extracts a Percentage from the Query\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [Quantity](#quantity)
      </td>

      <td>
        Extract a Quantity from a Query\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [Color](#color)
      </td>

      <td>
        Extracts a Color as both HEX and RGB codes from the Query\
        Variable Type: Object
      </td>
    </tr>

    <tr>
      <td>
        [TimeMeasurement](#time-measurement)
      </td>

      <td>
        Extracts a time measurement as (ns, mu, ms, s, min, h, d, week, month, year) Units\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [WeightMeasurement](#weight-measurement)
      </td>

      <td>
        Extracts a Weight Measurement as (mcg, mg, g, kg, oz, lb, mt, t) Units\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [CronSchedule](#cron-schedule)
      </td>

      <td>
        Extracts a one-time or recurring schedule as a CRON Expression from the Query\
        Variable Type: Object
      </td>
    </tr>

    <tr>
      <td>
        [OperatingSystem](#operating-system)
      </td>

      <td>
        Extracts the name of an Operating System (Windows, OSX, IOS, Android, Linux)\
        Variable Type: Object
      </td>
    </tr>

    <tr>
      <td>
        [QuantityofPeople](#quantity-of-people)
      </td>

      <td>
        Extracts the Number of People in a Query\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [VolumeMeasurement](#volume-measurement)
      </td>

      <td>
        Extracts a volume measurement as (mm3, cm3, ml, l, kl, m3, km3, tsp, Tbs, in3, fl-oz, cup, pnt, qt, gal, ft3, yd3) Units\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [TemperatureMeasurement](#temperature-measurement)
      </td>

      <td>
        Extracts a Temperature Measurement as (C, K, F) Units\
        Variable Type: Number
      </td>
    </tr>

    <tr>
      <td>
        [Person](#person)
      </td>

      <td>
        Extracts the name of a person(first and last names)\
        Variable Type: Object
      </td>
    </tr>

    <tr>
      <td>
        [DateTime](#datetime)
      </td>

      <td>
        Extracts date and time relative to the current date\
        Variable Type: Date
      </td>
    </tr>
  </tbody>
</table>

<br />

### Single Choice

The **Single Choice** is a type of input field that presents the user with a list of options to choose from. The user can only select **one** option from the list, and their choice is then stored as a value in a variable. This variable can be used later in your Workflow for further processing.

<Tip>
  Tip

  If the user enters text instead of clicking a button, the AI will check the text for any matching button labels. If it finds a match, it will handle the input as though the user had clicked that button.
</Tip>

An example of Single Choice would be a survey question with multiple options, where the user selects one answer from the list.

**Steps to use Single Choice Field**

1. Create a new capture information card.
2. Set the Type property to **Single Choice**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the selected option.
4. Set the **Prompt message** property to a message that lists the available options for the user to choose from.
5. Click on the **Advanced Configuration** to add Choices.

Once the card is used, it will present the available options to the user and allow them to select only one. The selected option will be saved in the Workflow variable you specified, and you can use it in other parts of your Workflow to make decisions or take actions based on the user's choice.

**Example**

Let's say you want to ask the user about their preferred mode of transportation, and you have three options: car, bus, and bike. You can create a new capture information card with the following properties:

```
Type: Single Choice
Variable name: preferredTransportation
Prompt message: What is your preferred mode of transportation? Choose one from the following: car, bus, bike.
```

When the user selects their preferred mode of transportation, the Single Choice card will save the value in the `preferredTransportation` Workflow variable. You can then use this variable to tailor the conversation based on the user's choice.

For example, if they choose bike, you can ask follow-up questions related to biking or suggest some scenic bike routes.

You can also use the value of the `preferredTransportation` variable in transitions. For example, if the user selects car, you can move them to a node related to car-related services or if they choose bus, you can move them to a node related to public transportation schedules.

### Multi Choice

The **Multi Choice** type is a way to gather information from users by presenting them with a list of options to choose from. Users can select one or more options from the list.

This type of capture information is useful in scenarios where you want to give users a set of choices to pick from, like selecting the toppings for a pizza or the colors for a shirt. It's a quick and easy way to collect information from users without having to ask them to type out their answers.

**Steps to use Multi Choice Field**

1. Create a new capture information card.
2. Set the Type property to **Multi Choice**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted values.
4. Set the **Prompt message** property to a message that provides a list of choices for the user to select from.
5. Click on the **Advanced Configuration** to add Choices.

Once the card is used, it will extract the selected options from the user's input and save them in the Workflow variable you specified. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

**Example**

Let's say you want to ask the user what toppings they want on their pizza. You can create a new capture information card with the following properties:

```
Type: Multi Choice
Variable name: pizzaToppings
Prompt message: What toppings would you like on your pizza? Please select all that apply: pepperoni, mushrooms, onions, olives, sausage.
```

When the user enters their response, the Multi Choice card will extract the selected options and save them in the `pizzaToppings` Workflow variable. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

For example, if the user selects **pepperoni** and **mushrooms,** you can use the `pizzaToppings` variable to customise their order and display a message like **Your pizza with pepperoni and mushrooms is on the way!**

### Boolean

**Boolean** type extracts a binary value from the user's input and saves it in a variable of type Boolean. The extracted information can include values like true and false, agree and disagree, accept and decline, or any other binary values.

**Steps to use Boolean Field**

1. Create a new capture information card.
2. Set the Type property to **Boolean**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted Boolean value.
4. Set the **Prompt message** property to a message that prompts the user to enter a binary value.
5. Optionally, you can edit the Choices property if you want to customize the binary values that the user can select. By default, the choices are **Yes** and **No**. When the user provides an input, the system will extract either a **true** or **false** value based on whether the user selects **Yes** or **No**.

**Example**

Let's say you want to ask the user if they agree to the terms and conditions of service. You can create a new capture information card with the following properties:

```
Type: Boolean
Variable name: agreeToTerms
Prompt message: Do you agree to the terms and conditions of our service? Please enter 'yes' or 'no'.
```

When the user enters their response, the Boolean card will extract the binary value and save it in the **agreeToTerms** Workflow variable as either true or false. You can then use this variable in other parts of your Workflow to decide whether to proceed with the service or not.

If the user agrees to the terms and conditions, you can submit their request or move them to the next node, but if they disagree, you can say something like 'Sorry to hear that' and end the conversation. This will display a message based on the user's response and whether they agreed to the terms and conditions or not.

### Confirmation

The **Confirmation** type is a way to ask the user to confirm or agree to something. For example, you might use this type to confirm a user's purchase, agreement to terms and conditions, or confirmation of an appointment. When the user responds, the Confirmation type extracts a binary value (either true or false) and saves it in a variable. This allows you to use the user's confirmation or agreement later in your bot's logic.

**Steps to use Confirmation Field**

1. Create a new capture information card.
2. Set the Type property to **Confirmation**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted Boolean value.
4. Set the **Prompt message** property to a message that prompts the user to confirm or agree to something.
5. Optionally, you can edit the Choices property if you want to customize the binary values that the user can select. By default, the choices are **Accept** and **Decline**. When the user provides an input, the system will extract either a **true** or **false** value based on whether the user selects **Accept** or **Decline**.

Once the card is used, it will automatically extract the confirmation from the user's input and save it in the Workflow variable you specified as a Boolean value (true or false). You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's confirmation.

**Example**

Let's say you want to ask the user if they want to proceed with a purchase. You can create a new capture information card with the following properties:

```
Type: Confirmation
Variable name: proceedWithPurchase
Prompt message: Are you sure you want to proceed with the purchase? Please enter 'Accept' or 'Decline'.
```

When the user enters their response, the Confirmation card will extract the confirmation and save it in the **proceedWithPurchase** Workflow variable as either true or false. You can then use this variable in other parts of your Workflow to decide whether to proceed with the purchase or not.

If the user confirms they want to proceed with the purchase, you can move them to the payment process node, but if they decline, you can say something like 'No problem, maybe next time!' and end the conversation. This will display a message based on the user's response and whether they confirmed to proceed with the purchase or not.

### Number

The**Number** type extracts a numerical value from the user's input and saves it in a variable of type number.

The user can enter any numerical value, like a whole number or a decimal, and the bot will recognize and store it as a number. This can be used for calculations or any other purpose where a numerical value is needed.

**Steps to use Number Field**

1. Create a new capture information card.
2. Set the Type property to **Number**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted numerical value.
4. Set the **Prompt message** property to a message that prompts the user to enter a numerical value.

Once the card is used, it will automatically extract the numerical value from the user's input and save it in the Workflow variable you specified as a numerical value (integer or decimal). You can then use this variable in other parts of your Workflow to perform calculations or take actions based on the user's response.

**Example**

Imagine you are creating an online store that sells products to customers. You want to ask the user to enter the quantity of a certain product they want to purchase. To do this, you can create a form with a field that uses the Number type to capture the user's input.

For example, you can create a field with the following details:

```
Type: Number
Variable name: productQuantity
Prompt message: How many units of this product would you like to purchase?
```

When the user enters their response, the Number field will extract the numerical value and save it in the `productQuantity` variable as either an integer or decimal value. You can then use this variable in other parts of your Workflow to calculate the total cost of the purchase.

For instance, if the product costs \$10 per unit and the user entered **3** as the product quantity, you can calculate the total cost in an [Execute Code Card](./execute-code) as follows:

```
workflow.totalCost = workflow.productQuantity * $10
```

This will enable you to calculate the total cost of the purchase based on the user's input and display it to the user before they confirm their order.

### Email Address

The **EmailAddress** type is used to extract an email address value from the user's input and save it in a variable of type string. This allows you to use the extracted email address in other parts of your bot's logic, such as sending an email confirmation or storing the email address for future use. The email address can be in any valid email address format, including with special characters such as dots, hyphens, and underscores.

**Steps to use Email Address Field**

1. Create a new capture information card.
2. Set the Type property to **EmailAddress**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted email address value.
4. Set the **Prompt message** property to a message that prompts the user to enter an email address.

Once the card is used, it will automatically extract the email address value from the user's input and save it in the Workflow variable you specified as a string value. You can then use this variable in other parts of your Workflow to send emails or perform other actions based on the user's response.

**Example**

Let's say you want to ask the user for their email address so that you can send them a newsletter. You can create a new capture information card with the following properties:

```
Type: EmailAddress
Variable name: userEmail
Prompt message: Please enter your email address to subscribe to our newsletter.
```

When the user enters their email address, the EmailAddress card will extract the value and save it in the `userEmail` Workflow variable as a string. You can then use this variable in other parts of your Workflow to add the user to your newsletter subscription list or perform other actions based on the user's response.

### Phone Number

In this section, we'll discuss the **PhoneNumber** capture information type in Botpress. This type of capture information extracts only the phone number representing the user's input, excluding the country code, and saves it in a variable of type string.

**Steps to use Phone Number Field**

1. Create a new capture information card.
2. Set the Type property to **PhoneNumber**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted phone number value.
4. Set the **Prompt message** property to a message that prompts the user to enter a phone number.

Once the card is used, it will automatically extract the phone number from the user's input and save it in the Workflow variable you specified as a string value. The extracted information won't include the country code, only the digits representing the phone number. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's phone number.

**Example**

Let's say you want to ask the user for their phone number to schedule a call with them. You can create a new capture information card with the following properties:

```
Type: PhoneNumber
Variable name: userPhoneNumber
Prompt message: Please enter your phone number so we can schedule a call with you.
```

When the user enters their response, the PhoneNumber card will extract the digits representing the phone number and save it in the userPhoneNumber Workflow variable as a string. You can then use this variable in other parts of your Workflow to schedule a call with the user.

### FullAddress

**FullAddress** extracts the full address information from the user's input and saves it in a variable of type object. The extracted information contains the country, city, street, zip code, and house number.

**Steps to use Full Address Field**

1. Create a new capture information card.
2. Set the Type property to **FullAddress**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted address information.
4. Optionally, set the **Prompt message** property to a message that prompts the user to enter their address.
5. Save the card.

Once the card is saved, it will automatically extract the full address information from the user's input and save it in the Workflow variable you specified. You can then use this variable in other parts of your Workflow by referencing the specific fields in the address object using the following syntax: **`{{Workflow.variableName.country}}`**, **`{{Workflow.variableName.city}}`**, **`{{Workflow.variableName.street}}`**, **`{{Workflow.variableName.zip}}`**, and **`{{Workflow.variableName.number}}`**.

**Example**

Let's say you want to capture the user's full address to use in a shipping process. You can create a new capture information card with the following properties:

```
Type: FullAddress
Variable name: shippingAddress
Prompt message: **Please enter your full shipping address:**
```

When the user enters their address, the FullAddress card will extract the information and save it in the `shippingAddress` Workflow variable. You can then use this variable in other parts of your Workflow to complete the shipping process, such as sending an email confirmation to the user with their shipping details.

Here's an example of how you can use the extracted information in a message:

```
Thank you for your order! Your shipping address is: {{workflow.shippingAddress.number}}
{{workflow.shippingAddress.street}}, {{workflow.shippingAddress.city}}, {{workflow.shippingAddress.country}},
{{workflow.shippingAddress.zip}}
```

This will display the user's full address in a clear and easy-to-read format for both the user and the bot.

### Price

**Price** extracts the price information from the user's input and saves it in a variable of type number. The extracted information contains the amount of money, regardless of the currency.

**Steps to use Price Field**

1. Create a new capture information card.
2. Set the Type property to **Price**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted price information.
4. Set the **Prompt message** property to a message that prompts the user to enter the price.
5. Optionally, set the **Default value** property to a default price to be used if the user doesn't provide one.
6. Save the card.

Once the card is saved, it will automatically extract the price information from the user's input and save it in the Workflow variable you specified. You can then use this variable in other parts of your Workflow to perform calculations or other operations that require the price information.

**Example**

Let's say you want to capture the user's price information to process a payment. You can create a new capture information card with the following properties:

```
Type: Price
Variable name: paymentAmount
Prompt message: Please enter the payment amount:
Default value: 0.00
```

When the user enters the price, the Price card will extract and save the information in the `paymentAmount` Workflow variable. You can then use this variable in other parts of your Workflow to process the payment, such as sending the payment information to a payment gateway.

Here's an example of how you can use the extracted information in a message:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Your payment amount is {{workflow.paymentAmount}}. Thank you for your payment!
```

This will display the user's payment amount in a clear and easy-to-read format for both the user and the bot.

### Raw Input

The **RawInput** extracts the user's input as it's and saves it in a variable of type string. The extracted information can include any type of user input, including text, numbers, and special characters.

**Steps to use Raw Input Field**

1. Create a new capture information card.
2. Set the Type property to **Raw Input**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted user input.
4. Set the **Prompt message** property to a message that prompts the user to enter their input.

Once the card is used, it will automatically extract the user's input and save it in the Workflow variable you specified as a string value. You can then use this variable in other parts of your Workflow to process the user's input or display it back to them.

**Example**

Let's say you want your users to submit an issue for your product. You can create a new capture information card with the following properties:

```
Type: Raw Input
Variable name: issueDescription
Prompt message: Please describe the issue you are experiencing.
```

When the user enters the issue description, the Raw Input card will extract the user's input and save it in the `issueDescription` Workflow variable as a string value. You can then use this variable in other parts of your Workflow to log the issue or escalate it to the relevant team for resolution.

You can create a message node with the following text:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Thank you for reporting the issue: {{issueDescription}}. Our team will investigate the issue and get back to you with an
update as soon as possible.
```

This will acknowledge the issue and provide the user with an estimated time frame for resolution.

##### Answer from a Knowledge Base

The Raw Input card can also be used to search for answers in a Knowledge Base (KB) and answer the user's question directly. You can have it search across all available KBs or limit the search to a specific KB.

**Searching All Knowledge Bases**

To enable the search across all available Knowledge Bases when the user asks a question:

1. Create a new capture information card with the Type set to **Raw Input**.
2. Make sure the "Search in all KBs" option is selected.
3. In the **Prompt message** property, enter a message that encourages the user to input their question (e.g., “What would you like to know?”).
4. Store the user's input in a variable by setting the **Variable name** property (e.g., `userQuery`) if you want to use it later.

Once set up, the bot will automatically search all configured Knowledge Bases for the user's inputted question and display the answer, provided that the Knowledge Agent's manual answering feature isn't enabled.

**Searching a Particular Knowledge Base**

For more targeted information retrieval, you may want to search within a specific KB:

1. Create a new capture information card with the Type set to **Raw Input**.
2. Deselect the "Search in all KBs" option.
3. Provide the name of the KB you wish to search in the "KBs to search in" input field.
4. In the **Prompt message** property, enter a prompt directing the user to ask their question.
5. Set the **Variable name** property to save the user's query (e.g., `userQuerySpecific`) if you want to use it later.

After the user submits their question, the bot will automatically conduct a search within the specified Knowledge Base and display the relevant answer. This happens seamlessly without the need for an action card to trigger the search, assuming that manual answering is turned off for the Knowledge Agent.

### Percentage

The **Percentage** extracts the decimal representing the percentage from the user's input and saves it in a variable of type number. The extracted information can include values like 50%, 75%, or any other percentage.

**Steps to use Percentage Field**

1. Create a new capture information card.
2. Set the Type property to **Percentage**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted percentage value.
4. Set the **Prompt message** property to a message that prompts the user to enter a percentage.

Once the card is used, it will automatically extract the decimal value representing the percentage from the user's input and save it in the Workflow variable you specified as a number value. You can then use this variable in other parts of your Workflow to make calculations or take actions based on the user's response.

**Example**

Let's say you want to ask the user what percentage discount they would like to apply to their purchase. You can create a new capture information card with the following properties:

```
Type: Percentage
Variable name: discountPercentage
Prompt message: **Please enter the percentage discount you would like to apply to your purchase.**
```

When the user enters their response, the Percentage card will extract the decimal value representing the percentage and save it in the `discountPercentage` Workflow variable as a number. You can then use this variable in other parts of your Workflow to calculate the discount or take actions based on the user's desired discount.

For example, if the user entered 50%, you could calculate the discount amount as follows:

```html theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
discountAmount = totalPrice * (discountPercentage / 100)
```

This will calculate the discount amount based on the user's desired discount percentage and the total price of the purchase.

### Quantity

The **Quantity** extracts the quantity information from the user's input and saves it in a variable of type number. For example, if the user inputs "I want to buy 5 apples" or "Give me 5 kilograms of apples", the function will extract the number 5 and store it as a numerical value, without regard to the different units of measurement used. This allows you to work with the quantity of the item, regardless of how the user expressed it.

**Steps to use Quantity Field**

1. Create a new capture information card.
2. Set the Type property to **Quantity**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted quantity information.
4. Set the **Prompt message** property to a message that prompts the user to enter the quantity.

Once the card is saved, it will automatically extract the quantity information from the user's input and save it in the Workflow variable you specified. You can then use this variable in other parts of your Workflow by referencing it using the following syntax: \***\*`{{Workflow.variableName}}`\*\***.

**Example**

Let's say you want to capture the user's desired quantity of a product. You can create a new capture information card with the following properties:

```
Type: Quantity
Variable name: productQuantity
Prompt message: **How many units of the product do you want?**
```

When the user enters a valid quantity, the Quantity card will extract and save the information in the `productQuantity` Workflow variable as a number. You can then use this variable in other parts of your Workflow to calculate the total price or to check the stock availability.

Here's an example of how you can use the extracted information in a message:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Thank you for your order! Your total price is {{workflow.productQuantity * productPrice}}.
```

This will display the total price to the user based on the quantity they entered and the price of the product.

### Color

The **Color** type extracts the color information from the user's input and saves it in a variable of type object. The extracted information contains the colour name, hexadecimal code, and RGB values.

**Steps to use Color Field**

1. Create a new capture information card.
2. Set the Type property to **Color**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted colour information.
4. Set the **Prompt message** property to a message that prompts the user to enter a colour.

Once the card is called will automatically extract the colour information from the user's input and save it in the Workflow variable you specified. You can then use this variable in other parts of your Workflow by referencing the specific fields in the colour object using the following syntax: **`{{workflow.variableName.colorName}}`**, **`{{workflow.variableName.hexCode}}`**, and **`{{workflow.variableName.rgb}}`**.

**Example**

Let's say you want to capture the user's favourite colour to use in a marketing campaign. You can create a new capture information card with the following properties:

```
Type: Color
Variable name: favoriteColor
Prompt message: Please enter your favourite colour:
```

When the user enters their favourite colour, the Color card will extract the information and save it in the `favoriteColor` Workflow variable. You can then use this variable in other parts of your Workflow to customise your marketing campaigns, such as using the colour in promotional materials or emails.

Here's an example of how you can use the extracted information in a message:

```html theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Thank you for telling us your favourite colour! We love {{workflow.favoriteColor.colorName}} too. The hexadecimal code
for {{workflow.favoriteColor.colorName}} is {{workflow.favoriteColor.hexCode}} and the RGB values are
{{workflow.favoriteColor.rgb}}.
```

This will display the user's favourite colour and its associated information in a personalised message, making the interaction with the bot more engaging and memorable.

### Time Measurement

The **TimeMeasurement** type extracts date/duration values from the user's input and save it in a variable of type **Number** after converting it to the chosen format. The extracted information can include values like next week, in a month, after two months, in 15 days, in 2 working days, etc. This information can be useful for scheduling appointments, setting reminders, and much more.

**Steps to use Time Measurement Field**

1. Create a new capture information card.
2. Set the Type property to **Time Measurement**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted time measurement value.
4. Set the **Prompt message** property to a message that prompts the user to enter a date/duration value.

Once the card is used, it will automatically extract the date/duration value from the user's input and save it in the Workflow variable you specified as a number value. The time measurement value will be converted to the chosen format (nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, weeks, months, or years). You can then use this variable in other parts of your Workflow to schedule appointments or set reminders.

**Available Formats**

The following formats are available for the extracted time measurement value:

`ns` (nanoseconds)\
`mu` (microseconds)\
`ms` (milliseconds)\
`s` (seconds)\
`min` (minutes)\
`h` (hours)\
`d` (days)\
`week` (weeks)\
`month` (months)\
`year` (years)

You can choose any of these formats based on your requirement.

**Example**

Let's say you want to schedule a meeting with a user based on their availability. You can create a new capture information card with the following properties:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Type: Time Measurement
Variable name: meetingTime
Prompt message: When are you available for a meeting? Please enter a date or duration (for example: next week, in 2 days, in 30 minutes).
```

When the user enters their response, the Time Measurement card will extract the time measurement value and save it in the `meetingTime` Workflow variable as a number value in the chosen format. You can then use this variable in other parts of your Workflow to schedule the meeting accordingly.

If the user is available at the specified time, you can schedule the meeting and confirm the details with the user. If not, you can ask for their availability again.

This will allow you to schedule meetings with users based on their availability and improve their experience with your service.

### Weight Measurement

The **WeightMeasurement** extracts weight information from the user's input and saves it in a variable of type number after converting it to the chosen format. The available formats are `mcg`, `mg`, `g`, `kg`, `mt`, `oz`, `lb`, `t`.

**Steps to use Weight Measurement Field**

1. Create a new capture information card.
2. Set the Type property to **Weight Measurement**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted weight value.
4. Set the **Prompt message** property to a message that prompts the user to enter a weight.

Once the card is used, it will automatically extract the weight information from the user's input and save it in the Workflow variable you specified as a number value. The value is converted to the chosen format which is selected during the configuration of the card. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

**Available Formats**

The available weight measurement formats are:

<table>
  <thead>
    <tr>
      <th>mcg (microgram)</th>
      <th>mg (milligram)</th>
      <th>g (gram)</th>
      <th>kg (kilogram)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>mt (metric ton)</td>
      <td>oz (ounce)</td>
      <td>lb (pound)</td>
      <td>t (ton)</td>
    </tr>
  </tbody>
</table>

**Example**

Let's say you want to ask the user for their weight in kilograms. You can create a new capture information card with the following properties:

```
Type: Weight Measurement
Variable name: userWeight
Prompt message: Please enter your weight in kilograms.
```

When the user enters their response, the Weight Measurement card will extract the weight information and convert it to kilograms, saving it in the `userWeight` Workflow variable as a number value. You can then use this variable in other parts of your Workflow to decide what to do based on the user's response.

You can ask the user if they want to proceed if their weight is over a certain limit or if it falls under a certain range. You can also display the weight measurement in different formats by using a formatted node.

This will display the user's weight in the desired format and provide relevant information based on their response.

### Cron Schedule

The **CronSchedule** type takes a specific interval of time that a user inputs and convert it into a format that a computer program can understand. This interval can be things like **every 5 minutes** or **once a day at 3pm.**

The cron schedule then saves this interval in two ways: first, in a format that follows the cron convention (which is a standard way of representing time intervals in programming); and second, as a Boolean value that indicates whether the interval should be repeated or not (for example, if the interval is "every 5 minutes," the cron schedule would set the repeatable property to true, whereas if the interval is "once a day at 3pm," the cron schedule would set the repeatable property to false).

This makes it easier for developers to program applications that need to run certain tasks at specific intervals of time.

**Steps to use cron schedule field**

1. Create a new capture information card.
2. Set the Type property to **cron schedule**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted cron interval.
4. Set the **Prompt message** property to a message that prompts the user to enter the desired interval value.

Once the card is used, it will automatically extract the interval value from the user's input and save it in the Workflow variable you specified as an object containing the cron interval and the **repeatable** Boolean value.

**Example**

Let's say you want to ask the user for a cron schedule to trigger a certain event. You can create a new capture information card with the following properties:

```
Type: Cron Schedule
Variable name: cronSchedule
Prompt message: Please enter the interval in cron format, for example: '0 \* \* \* \*' for every hour, and indicate whether this should be repeated or not with 'true' or 'false'.
```

When the user enters their response, the cron Schedule card will extract the interval value and save it in the `cronSchedule` Workflow variable as an object with two properties: the **cron** value, which represents the extracted interval in a cron format, and the **repeatable** Boolean value, which indicates whether the interval should be repeated or not.

You can then use this variable in other parts of your Workflow to set up the event trigger according to the user's input.

### Operating System

The **OperatingSystem** type extracts the operating system the user is using from their input and saves it in a variable of type object. This information can be useful for troubleshooting issues specific to certain operating systems or for tailoring responses based on the user's operating system.

**Steps to use Operating System Field**

1. Create a new capture information card.
2. Set the Type property to **Operating System**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted operating system.
4. Set the **Prompt message** property to a message that prompts the user to enter their operating system.

Once the card is used, it will automatically extract the operating system from the user's input and save it in the Workflow variable you specified as an object. The extracted information can include the name and version of the operating system.

**Example**

Let's say you want to ask the user about the operating system they're using to access your website. You can create a new capture information card with the following properties:

```
Type: OperatingSystem
Variable name: userOS
Prompt message: **What operating system are you using to access our website?
```

When the user enters their response, the Operating System card will extract the information and save it in the **userOS** Workflow variable as an object that includes the name and version of their operating system.

You can then use this variable in other parts of your Workflow to tailor responses or troubleshoot issues specific to their operating system.

### Quantity of People

The **QuantityofPeople** type extracts a number representing the quantity of people from the user's input and saves it in a variable of type **Number**. The extracted information can include values like 1, 2, or 3.

For example, if you are building a reservation system for a restaurant, you can use the QuantityofPeople type to ask the user how many people will be dining, and then save that number as a variable. This variable can then be used to ensure that the restaurant has enough seats available for the group, or to calculate the total cost of the meal based on the number of people.

**Steps to use Quantity of People Field**

1. Create a new capture information card.
2. Set the Type property to **QuantityofPeople**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted number value.
4. Set the **Prompt message** property to a message that prompts the user to enter a number representing the quantity of people.

Once the card is used, it will automatically extract the number value from the user's input and save it in the Workflow variable you specified as a number. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

**Example**

Let's say you want to ask the user how many people will be attending an event. You can create a new capture information card with the following properties:

```
Type: Quantity Of People
Variable name: numberOfAttendees
Prompt message: How many people will be attending the event?
```

When the user enters their response, the Quantity Of People card will extract the number value and save it in the **numberOfAttendees** Workflow variable. You can then use this variable in other parts of your Workflow to decide how many seats to reserve or how much food to order.

If the user enters a number greater than the available seats or food quantity, you can respond with something like 'Sorry, we don't have enough seats/food for that many people' and ask the user to enter a smaller number.

This will display a message based on the user's response and the availability of seats or food.

### Volume Measurement

The **VolumeMeasurement** extracts a volume value from the user's input and saves it in a variable of type number. The extracted value can be converted to one of the several available formats based on the user's choice.

**Steps to use Volume Measurement Field**

1. Create a new capture information card.
2. Set the Type property to **VolumeMeasurement**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted volume value.
4. Set the **Prompt message** property to a message that prompts the user to enter a volume value.

Once the card is used, it will automatically extract the volume value from the user's input and save it in the Workflow variable you specified as a number value. You can then use this variable in other parts of your Workflow to perform calculations or use the value in responses to the user.

**Available Formats**

The following volume formats are available for conversion:

<table>
  <thead>
    <tr>
      <th>
        Cubic millimeters (mm<sup>3</sup>)
      </th>

      <th>
        Cubic centimeters (cm<sup>3</sup>)
      </th>

      <th>Milliliters (ml)</th>
      <th>Centiliters (cl)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Deciliters (dl)</td>
      <td>Liters (l)</td>
      <td>Kiloliters (kl)</td>

      <td>
        Cubic meters (m<sup>3</sup>)
      </td>
    </tr>

    <tr>
      <td>
        Cubic kilometers (km<sup>3</sup>)
      </td>

      <td>Teaspoons (tsp)</td>
      <td>Tablespoons (Tbs)</td>

      <td>
        Cubic inches (in<sup>3</sup>)
      </td>
    </tr>

    <tr>
      <td>Fluid ounces (fl-oz)</td>
      <td>Cups (cup)</td>
      <td>Pints (pnt)</td>
      <td>Quarts (qt)</td>
    </tr>

    <tr>
      <td>Gallons (gal)</td>

      <td>
        Cubic feet (ft<sup>3</sup>)
      </td>

      <td>
        Cubic yards (yd<sup>3</sup>)
      </td>

      <td />
    </tr>
  </tbody>
</table>

**Example**

Let's say you want to ask the user about the volume of a liquid they want to order. You can create a new capture information card with the following properties:

```
Type: VolumeMeasurement
Variable name: liquidVolume
Prompt message: What is the volume of liquid you want to order? Please enter a number and choose a volume format from the following list: mm3, cm3, ml, cl, dl, l, kl, m3, km3, tsp, Tbs, in3, fl-oz, cup, pnt, qt, gal, ft3, yd3.
```

The **Volume Measurement** type extracts the volume value and save it in the `liquidVolume` Workflow variable as a number value. The value will be converted to the format specified by the user. You can then use this variable in other parts of your Workflow to perform calculations or use the value in responses to the user.

For example, you could use the `liquidVolume` variable to calculate the price of the liquid based on the volume and price per unit of volume, or you could use it in response to the user like **Thank you for ordering** `{{workflow.liquidVolume}}` **ml of liquid.** Your order will be delivered soon.

### Temperature Measurement

The **TemperatureMeasurement** type extracts a temperature value from the user's input and saves it in a variable of type **Number**. The extracted temperature can be in any of the available formats: Celsius, Kelvin, or Fahrenheit.

**Steps to use Temperature Measurement Field**

1. Create a new capture information card.
2. Set the Type property to **Temperature Measurement**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted temperature value.
4. Set the **Prompt message** property to a message that prompts the user to enter a temperature value in any of the available formats.

Once the card is used, it will automatically extract the temperature value from the user's input, convert it to the chosen format, and save it in the Workflow variable you specified as a number. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

**Available Formats**

There are three temperature formats available in the **TemperatureMeasurement** capture information type. These are: Celsius (°C), Kelvin (K) & Fahrenheit (°F)

You can choose the format you want to use in the prompt message property of the capture information card.

**Example**

Let's say you want to ask the user for their body temperature. You can create a new capture information card with the following properties:

```
Type: TemperatureMeasurement
Variable name: bodyTemperature
Prompt message: Please enter your body temperature in Celsius (°C), Kelvin (K), or Fahrenheit (°F)
```

When the user enters their response, the Temperature Measurement card will extract the temperature value, convert it to the specified format, and save it in the `bodyTemperature` Workflow variable as a **Number**. You can then use this variable in other parts of your Workflow to decide what action to take based on the user's body temperature.

If the user's body temperature is above the normal range, you can send them to a doctor's appointment node. If not, you can proceed with the conversation as usual.

This will display a message based on the user's response and the action you decide to take based on their body temperature.

### Person

The **Person** type is used to extract the name of a person from the user's input, such as when you ask the user for the name of a contact or a customer. Once the user enters the name, the Person type extracts the first and last names and saves them in a variable of type **Object**.

This extracted information can be used in other parts of your Workflow to personalize messages or perform actions specific to that person, such as sending them an email or adding them to a mailing list.

**Steps to use Person Field**

1. Create a new capture information card.
2. Set the Type property to **Person**.
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted name information.
4. Optionally, set the **Prompt message** property to a message that prompts the user to enter their name.
5. Save the card.

Once the card is saved, it will automatically extract the person's name information from the user's input and save it in the Workflow variable you specified.

You can then use this variable in other parts of your Workflow by referencing the specific fields in the name object using the following syntax:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{{workflow.variableName.first}} and {{workflow.variableName.last}}
```

**Example**

Let's say you want to capture the user's name to personalise a message. You can create a new capture information card with the following properties:

```
Type: Person
Variable name: userName
Prompt message: What's your name?
```

When the user enters their name, the Person card will extract and save the information in the **userName** Workflow variable. You can then use this variable in other parts of your Workflow to personalise your messages, such as greeting the user by name.

Here's an example of how you can use the extracted information in a message:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Hello {{workflow.userName.first}}, welcome to our website!
```

This will display a personalised greeting to the user with their first name.

### Datetime

The **Datetime** capture information type in Botpress. This type of capture information extracts a date or duration value from the user's input and saves it in a variable of type **Object**. The extracted information can include values like **next week,** **in a month,** **after two months,** **in 15 days,** **2 working days,** or any other date or duration value.

**Steps to use Datetime Field**

1. Pick the **Datetime** Capture Information Card from the Cards.
2. (Optional) - Add a question to ask. (for example: when would you like to book an appointment?)
3. Store the output in a variable.

Once the card is used, it will automatically extract the date or duration value from the user's input and save it in the Workflow variable you specified as an object. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

**Example**

Let's say you want to ask the user for their preferred date of booking a hotel room. You can create a new capture information card with the following properties:

```
Type: Datetime
Variable name: bookingDate
Prompt message: When would you like to book the room? Please enter a date or duration (e.g., next week, in a month, after two months, in 15 days, 2 working days).
```

When the user enters their response, the Datetime card will extract the date or duration value and save it in the `bookingDate` Workflow variable as an object. You can then use this variable in other parts of your Workflow to decide when to book the room or provide available dates for the user to choose from.

You can check the user's preferred booking date against your available dates to ensure the room is available for booking on that day. If the room isn't available, you can offer other available dates or suggest another hotel that's available on the preferred date.

##### Formatting Date

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const date = luxon.DateTime.fromJSDate(workflow.date)
// Default format of date is 2023-09-27T00:00:00.000Z

// Example 1: Display a Friendly, Human-readable Date Format
const friendlyFormat = date.toFormat('LLLL dd, yyyy')
console.log(`📅 Your requested date is: ${friendlyFormat}.`)
// Output: 📅 Your requested date is: September 27, 2023.

// Example 2: Display the Day of the Week
const dayOfWeek = date.toFormat('EEEE')
console.log(`📆 It falls on a: ${dayOfWeek}.`)
// Output: 📆 It falls on a: Wednesday.

// Example 3: Display the Date in Numeric Format
const numericDateFormat = date.toFormat('dd-MM-yyyy')
console.log(`🗓 Numeric Format: ${numericDateFormat}.`)
// Output: 🗓 Numeric Format: 27-09-2023.

// Example 4: Display the Date with Slashes
const slashDateFormat = date.toFormat('yyyy/MM/dd')
console.log(`📌 Slash Format: ${slashDateFormat}.`)
// Output: 📌 Slash Format: 2023/09/27.

// Example 5: Display the Date with Day and Month Name
const dayMonthNameFormat = date.toFormat('EEEE, dd of LLLL')
console.log(`🌟 Day and Month Name Format: ${dayMonthNameFormat}.`)
// Output: 🌟 Day and Month Name Format: Wednesday, 27 of September.
```

### Wait for User Input

The **Wait for User Input** type is used to pause the Workflow of a conversation until the user enters a specific input. This can be useful when you want to wait for the user to enter a specific input before proceeding with the conversation.

**Steps to use Wait for User Input Field**

1. Drag and drop the **Wait for User Input** card into your node.
2. You can use `{{event.preview}}` to display the fetched user's response after the user enters the input.

### File Upload

The **File Upload** type allows users to upload a file through the bot interface. Once the file is uploaded, the bot captures the URL of the uploaded file as a string variable.

##### Configuration Steps:

1. **Enable File Upload in Webchat Settings**:
   * Navigate to the **Webchat** settings in Botpress Studio.
   * Under the **General** tab, find the option labeled **Allow user file upload**.
   * Toggle the setting to **Enabled**.

2. **Set Up the Capture Information Card**:
   * In the **Capture Information** card, select **File** as the **Type of value to extract**.
   * Define the **Question to ask the user**, such as "Please upload the file you want to share."
   * Specify the variable in **Store result in** where the file URL will be stored (e.g., `workflow.filePath`).

##### Example:

If the user uploads a file, the bot will save the file's URL to the specified variable. You can then use this variable in subsequent Workflows, such as storing the file URL in a database or sending it to an API.

## Custom Prompt Fields

### Entity - Regex

The **Entity - Regex** type of capture information uses regular expressions to extract specific patterns of information from the user's input and saves it in a variable of type **String**. It's particularly useful for capturing sensitive information like credit card numbers, which have distinct patterns.

**Steps to use Regex Field**

1. Create a new entity in the **Entities** section of your Botpress instance with a custom regular expression that matches the pattern of the information you want to capture.
2. Create a new capture information card.
3. Set the Type property to **Entity Regex**.
4. Select the entity you created in Step 1 from the **Entity** dropdown.
5. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted information.
6. Set the **Prompt message** property to a message that prompts the user to enter the information you want to capture.

Once the card is used, it will automatically extract the information that matches the regular expression pattern from the user's input and save it in the Workflow variable you specified as a string. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's input.

**Example**

Let's say you want to ask the user for their credit card number. You can create a new entity with a regular expression that matches the pattern of a credit card number, such as **/(\d\{4}-)\{3}\d\{4}/** for a 16-digit credit card number in the format **XXXX-XXXX-XXXX-XXXX**. You can then create a new capture information card with the following properties:

```
Type: Entity Regex
Entity: Credit Card Number (the entity you created in step 1)
Variable name: creditCardNumber
Prompt message: Please enter your credit card number in the format XXXX-XXXX-XXXX-XXXX.
```

When the user enters their credit card number, the Entity Regex card will extract the credit card number that matches the regular expression pattern and save it in the **creditCardNumber** Workflow variable as a string. You can then use this variable in other parts of your Workflow to perform actions like validating the credit card number or sending it to a payment gateway.

It's important to note that the **Contains sensitive data** property is available for Entity Regex type, which will mask the data by \* before saving it in the database, making it more secure.

### Entity - List

In this section, we'll discuss the **Entity - List** capture information type in Botpress. This type of capture information extracts specific pieces of information from the user's input based on matching it with entries (or synonyms) in a custom entity list. This can be useful when you want to capture specific information like a person's name, location, or product name.

**Steps to use List Field**

1. Create a new entity list under the library -> entities section.
2. Add entries to the entity list and their synonyms.
3. Create a new capture information card.
4. Set the Type property to **Entity List**.
5. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted information.
6. Set the **Prompt message** property to a message that prompts the user to enter information that matches the entity list.

Once the card is used, it will automatically extract the information that matches an entry (or one of its synonyms) in the custom entity list from the user's input and save it in the Workflow variable you specified. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's response.

**Fuzzy matching options**

Botpress offers three options for fuzzy matching:

* **Strict**: No errors allowed.
* **Medium**: Tolerates up to one error in words of four characters or more.
* **Loose**: Tolerates up to two errors in words of four characters or more.

This means that even if the user makes a typo or a slight error, the system can still match the input with an entry in the entity list.

**Example**

Let's say you want to ask the user for their favorite type of pizza. You can create a new entity list with entries like **Pepperoni,** **Hawaiian,** **Margherita,** and **Vegetarian.** Then, create a new capture information card with the following properties:

```
Type: Entity List
Variable name: favoritePizza
Prompt message: **What's your favorite type of pizza? Please enter the name of one of our popular pizza types.
```

When the user enters their response, the Entity List card will extract the information that matches an entry (or synonym) in the custom entity list and save it in the `favoritePizza` Workflow variable. You can then use this variable in other parts of your Workflow to make decisions or take actions based on the user's favorite pizza type.

For example, you could use this variable to direct the user to the pizza ordering process, or to suggest additional toppings based on their selection.

## Advanced Configuration

### Retries

The **Retries** setting helps the bot handle situations when it doesn't understand what the user is saying. It allows the bot to ask the user to provide the information again in a different way. This can improve the user's experience with the bot, increase engagement, and help the bot handle more conversations before giving up.

**Number of retries**

This is the maximum number of times the bot will ask the user to provide the information again before giving up and moving to the next card in the conversation or triggering the failure transition if enabled.

**Retry message**

This is the message that the bot will show to the user each time they fail to answer the question. It will ask the user to provide the information again in a different way. If the capture has predefined choices the retry message will contain the buttons again.

You can also add variables to this message using the following syntax:

```
Hello @workflow.userName.first, we did not get your number right, please enter it again!
```

**Pro Tip**

To give your users the best experience, you can combine the **Retries** option with the **Add transition to handle failure** flag. This will help the bot gracefully handle situations when it can't understand the user's input.

**Example 1:**

Let's say you have a card that asks the user to choose between **Food** and **Drinks**. If you set the **Number of retries** to 0 and the **Add transition to handle failure** flag is turned on, then if the user says **I want Cars**, the bot will redirect the user directly to the failure transition, where you can show a message like **Sorry, I didn't understand that**.

**Example 2:**

Now, let's change the example to have the **Number of retries** set to 2 and the **Retry message** set to **Sorry, I didn't understand that, try to choose from the choices**, and the **Add transition to handle failure** flag turned on. If the user says, **I want Cars**, the bot will respond with **Sorry, I didn't understand that. Try to choose from the choices**, and show the choices again.

If the user provides another message that isn't related to the choices, the bot will retry again, up to a maximum of two retries. If the user still fails to provide the required information after the maximum retries, the bot will redirect the user directly to the failure transition, where you can have a message like **Sorry, I didn't understand that**.

### Validation

The **Validation** setting allows you to verify that the user's input meets certain criteria before proceeding with the conversation. This can help ensure that the information collected is accurate and relevant to the conversation.

**Properties**

**1. Label**

The label property allows you to generate validation code based on plain natural language instructions. This can make it easier to set up the validation rules without needing to write code.

**2. Code**

If you prefer to write your own validation code, you can use the code property. This property allows you to write code to evaluate the user's input and determine whether it meets the validation criteria.

**3. Validation failed message**

If the user's input fails validation, you can customise the message that the bot sends to inform the user of the validation failure.

**Steps to use Validation**

To use the validation feature, you can add the validation properties to the Capture Information card in the Botpress interface. You can choose to use the Label or Code property to set up the validation rules.

Once the validation rules are set up, the user's input will be evaluated before proceeding with the conversation. If the input meets the validation criteria, the conversation will continue normally. If the input fails validation, the bot will send a message with the validation failed message you have specified.

**Example 1:**

Suppose you have a Capture Information card that asks the user for their age. You want to ensure that the user enters a number between 18 and 100. You can use the following validation code in the **Validation** section of the card:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function validate(input: string): boolean
{
  const age = parseInt(input) if (isNaN(age))
  { return false }
  return age >= 18 && age <= 100
}
```

This code first tries to parse the user's input as a number. If the input isn't a valid number, the code returns **false**. Otherwise, it checks if the age is between 18 and 100 and returns **true** if it is.

**Example 2:**

Suppose you have a Capture Information card that asks the user for their email address. You want to ensure that the user enters a valid email address format. You can use the following validation code in the **Validation** section of the card:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function validate(input: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
  return emailRegex.test(input)
}
```

This code uses a regular expression to check if the user's input matches the format of a valid email address. If the input matches the format, the code returns `true`. Otherwise, it returns `false`.

### Extract from History

The **Extract from History** setting allows the bot to extract values from previous messages in the conversation history. This can help the bot better understand the user's input and provide more accurate responses.

**Property**

**Number of messages from history to extract from**

This property determines how many messages in the conversation history the bot will try to extract the value from. A value of **0** means that the bot won't look back in the conversation history and will only use the user's most recent message. A value of **2** means that the bot will extract the value from the user's previous two messages.

**Example:**

Let's say you have a Capture Information card that asks the user for their favorite color. If the user has already mentioned their favorite color earlier in the conversation, you can use the **Extract from History** feature to extract the value from their previous message.

If you set the **Number of messages from history to extract from** to **1**, the bot will extract the value from the user's previous message. If you set it to **2**, the bot will extract the value from the message before that too.

For example, if the user said **My favorite color is blue** earlier in the conversation and you set the **Number of messages from history to extract from** to **1**, the bot will extract **blue** as the user's favorite color without asking the user again. This can save time and improve the user experience by avoiding repetitive questions.

### Cancellation

The **Cancellation** setting can be used to break out of the conversation and cancel the Capture Information card. This can enhance the user's experience with the bot, making the conversation feel more natural and increasing engagement.

**Properties**

**User can cancel the capture**

With this option turned on, users can cancel the Capture Information card at any time during the conversation.

**Confirm before cancelling**

If you turn on this option, users will be asked to confirm whether they want to cancel the Capture Information card before it's cancelled.

**Confirm cancel message**

This option allows you to customise the message that the bot sends to confirm the user's decision to cancel the Capture Information card.

**Example 1:**

Suppose you have a Capture Information card that asks the user for their name and email address. If the user decides to cancel the conversation, the **User can cancel the capture** option will allow them to do so easily.

**Example 2:**

If you turn on the **Confirm before cancelling** option, the bot will ask the user if they're sure they want to cancel the Capture Information card before it's cancelled. If the user confirms the cancellation, the bot will send a message that you can customise using the **Confirm cancel message** option.

### Choices

The **Choices** setting is used to offer a list of options to the user as a response to a Capture Information card. This can be useful when you want to restrict the user's input to a specific set of values or provide them with a list of options to choose from quickly.

You could add fixed options or add variables to each choice to make them dynamic. You can also render the list of choices dynamically by toggling the SuperText input and adding an array variable with the following format:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
;[
  {
    label: 'French',
    value: 'fr',
  },
  {
    label: 'English',
    value: 'en',
  },
]
```

<Warning>
  Limit

  If you add more than 5 choices, they will be rendered as a Dropdown/List instead of buttons. This number may vary by channel.\{' '} The choices labels shouldn't be longer than 20 characters otherwise they will get cut in some channels.
</Warning>

<Tip>
  To show a **dropdown** when you have **five or fewer** choices, or to control options entirely in code, see [Dropdown menus](/docs/studio/guides/how-to/dropdown-menus).
</Tip>

<Note>
  Note

  Choices are only available for **Single Choice**, **Multiple Choice**, **Boolean**, **Confirmation** and **Raw Input**Capture cards.
</Note>

**Example**

Suppose you have a Capture Information card that asks the user to select their preferred mode of transportation - Car, Bus or Train. If you turn on the Choices option and specify these three options, the user will be presented with these options to choose from.

### Advanced

1. Add transition to handle failure

This is a yes/no flag that determines whether a transition should be added to handle cases where the Capture Information card fails to retrieve information from the user.

**Example**

If this flag is set to **Yes** and the Capture Information card fails to capture the required information, it will transition to the failure transition where a message can be displayed to the user, such as **Sorry, I didn't understand that. Please try again**.

2. Skip if variable is already filled

This is a flag that determines whether the Capture Information card should be skipped if the variable assigned to it already has a value.

**Example**

If this flag is set to **Yes** and the variable already has a value, the Capture Information card will be skipped entirely, and the conversation will proceed to the next node.

This flag can be useful in scenarios where a user may have already provided the required information in a previous conversation with the bot.

Combining these two flags can help improve the user experience with the bot by allowing for smoother conversation Workflows and avoiding unnecessary repetition.

## Prompt Chaining

Prompt Chaining allows you to extract multiple values from a single user message using multiple Capture Information cards in sequence. If a value wasn't found, the respective Capture Information card will ask for its value.

**Chaining Multiple Prompts**

To chain multiple Capture Information cards together, you need to follow these steps:

1. Add the first Capture Information card to the Workflow.
2. Set the Type property to the type of information you want to capture (e.g., **Person Name**).
3. Set the **Variable name** property to the name of the Workflow variable you want to use to store the extracted information (e.g., **Person Name**).
4. Set the **Prompt message** property to a message that prompts the user to enter the information (e.g., **Please enter your full name**).
5. Set the **Extract from history** property to **1**.
6. Add the next Capture Information card to the Workflow.
7. Repeat steps 1-6 for each additional Capture Information card you want to add, making sure to use a different variable name for each one.

Once the user enters a value, it will automatically extract the requested information from the user's message using each Capture Information card in sequence. If a value isn't found for a particular Capture Information card, it will ask the user for the value before proceeding to the next node/card.

You can then use the extracted variables in other parts of your Workflow by referencing the specific variable names using the following syntax: **`{{workflow.variableName}}`**.

**Example**

Let's say you want to capture a user's full name, email address, and phone number. You can create a new Workflow with the following steps:

1. Add a Capture Information card to the Workflow with the following properties:

```
Type: Fullname
Variable name: fullname
Prompt message: Please enter your full name
Extract from history: 1
```

2. Add a second Capture Information card to the Workflow with the following properties:

```
Type: Email
Variable name: email
Prompt message: Please enter your email address
Extract from history: 1
```

3. Add a third Capture Information card to the Workflow with the following properties:

```
Type: PhoneNumber
Variable name: phone
Prompt message: Please enter your phone number
Extract from history: 1
```

When the user sends a message, the Workflow will begin extracting the requested information from the user's message using each Capture Information card in sequence. If a value isn't found for a particular Capture Information card, it will ask the user for the value before proceeding to the next card.

You can then use the extracted variables in other parts of your Workflow, such as sending a confirmation message to the user with their captured information:

```
Thank you for submitting your information!
We have your full name as {{workflow.fullname.first}} {{workflow.fullname.last}}, your email address as {{workflow.email}}, and your phone number as {{workflow.phone}}.
We'll be in touch soon!
```

This will display the user's captured information in a clear and easy-to-read format for both the user and the bot.


# Execute Code
Source: https://botpress.com/docs/studio/concepts/cards/execute-code



The Execute Code Card lets you **run custom [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) code within a Node**.

You can use the Execute Code Card to extend the functionality of your bot beyond Studio's built-in Cards. For example, you can:

* Perform complex calculations
* Manipulate data and variables (see [variables in code](/docs/studio/concepts/variables/in-code))
* Call external APIs
* Add guardrails such as custom error handling, rate limits, permission checks, and fallbacks

<Note>
  Execute Code Cards allow you to generate one-time code snippets at specific points in your Workflow. For reusable code snippets, use [Actions](/docs/studio/concepts/actions).
</Note>

<Warning>
  You can't import external libraries within an Execute Code Card. To make API requests, you can use [Axios](https://axios-http.com/docs/intro).
</Warning>

## Generate code using AI

The Execute Code card allows you to generate code using AI, so you don't have to write it all from scratch:

<Frame>
  <img alt="Generate code using AI" />

  <img alt="Generate code using AI" />
</Frame>

At the top of the code editor, write a prompt and hit enter to generate code using AI. You can then edit this code manually or ask AI to make revisions to it.

<Note>
  Review AI-generated code before production. Store secrets in [configuration variables](/docs/studio/concepts/variables/scopes/configuration) (use `env` in code), and handle slow or failed requests with `try`/`catch`, timeouts, or fallback flows.
</Note>


# Fixed Schedule
Source: https://botpress.com/docs/studio/concepts/cards/fixed-schedule

Schedule a part of your Workflow.

The **Fixed Schedule** Card lets you trigger some part of your Workflow at a specific time.

<Tip>
  You can use the Fixed Schedule Card to [send reminders to your users](/docs/studio/guides/how-to/send-reminders).
</Tip>

## Add the Card

To add the Fixed Schedule Card:

<Steps>
  <Step title="Open the Trigger menu">
    Right-click anywhere in your Workflow. Then, hover over the Trigger menu:

    <img alt="Trigger menu" />
  </Step>

  <Step title="Add the Fixed Schedule Card">
    Select **Fixed Schedule** to add the Card:

    <img alt="Fixed Schedule Card" />
  </Step>
</Steps>

## Schedule the Card

You can use the Card's settings to schedule when it executes:

<img alt="Fixed Schedule Options" />

## Set a Custom Schedule

You can use a cron expression to set a custom schedule for the Card.

<Tip>
  To learn about cron expressions and test them out yourself, check out [crontab guru](https://crontab.guru).
</Tip>

In the Card's scheduling options, select **Custom** to open the cron field:

<img alt="cron Settings" />

The Card will preview when the trigger is scheduled, or let you know if your cron expression is invalid:

<img alt="Invalid cron" />


# Flow Logic
Source: https://botpress.com/docs/studio/concepts/cards/flow-logic



Flow Logic Cards **direct the flow of your bot's conversation** based certain conditions. You can use them to guide the conversation based on user input, bot state, or external factors.

There are two Flow Logic Cards available in the Card tray:

## Expression

The Expression Card evaluates custom expressions or conditions to make decisions within your Workflow. You can use it to transition to a Node based on a condition:

* If the condition evaluates to `true`, your bot will transition to whatever Node is connected to the Expression Card
* If the condition evaluates to `false`, your bot will skip the Card and continue its execution

There are two ways to describe conditions for a transition:

### Natural language

You can describe the condition using natural language. In the Card's **Label** field, describe the condition, then press <kbd>Enter</kbd>. This automatically updates the **Condition** field with an AI-generated [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) expression that corresponds to your condition.

<Accordion title="Examples">
  Here are some examples of conditions you could enter in the **Label** field:

  | Example                                                         | Description                                                                                                                    |
  | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
  | User input                                                      | To check if the user entered a value between 1 and 10. <br />Example: *user input is between 1 & 10*                           |
  | [User variable](/docs/studio/concepts/variables/scopes/user)         | To check a user variable, use **`user.{variable name}`**. <br />Example: *`user.language` is "English"*                        |
  | [Workflow variable](/docs/studio/concepts/variables/scopes/workflow) | To check a Workflow variable, use **`workflow.{variable name}`**. <br />Example: *`workflow.supportEmail` contains "Botpress"* |
</Accordion>

### Code

You can also describe the condition manually using a JavaScript expression:

1. To the right of the **Condition** field, toggle <AiIcon /> to disable generative AI for the field.

2. Enter a valid JavaScript expression in the **Condition** field.

## Intent

<Warning>
  The Intent Card is **deprecated**—use the [AI Transition](/docs/studio/concepts/cards/ai/ai-transition) Card instead. Any existing Intent Cards in your Workflows will still work as expected.
</Warning>

The **Intent** Card is used to direct the conversation's flow based on the user's recognized intent. Intents are predefined categories of user input that represent what the user wants to achieve, such as booking an appointment, asking for help, or providing feedback.

When an Intent Card is triggered, it checks if the user’s input matches any of the defined intents and routes the conversation accordingly.

There are two ways to define the intent you want to trigger using this card:

1. By selecting a predefined intent from your Library
2. By defining an inline intent that only exists for this card.


# Cards
Source: https://botpress.com/docs/studio/concepts/cards/introduction



Cards are drag-and-drop elements that **perform tasks within a [Node](/docs/studio/concepts/nodes)**:

<Frame>
  <img alt="Cards" />

  <img alt="Cards" />
</Frame>

You can use Cards to:

<CardGroup>
  <Card title="Send messages" href="/studio/concepts/cards/send-messages">
    Send text, images, and other content to users
  </Card>

  <Card title="Control Workflow logic" href="/studio/concepts/cards/flow-logic">
    Transition to another Workflow
  </Card>

  <Card title="Execute code" href="/studio/concepts/cards/execute-code">
    Add custom JavaScript code to your Workflow
  </Card>
</CardGroup>

This section contains documentation for all Cards in the Studio.

## Add a Card

1. Select **+ Add Card** on any Node to open the Card tray.
2. Select any Card to add it to your Node.

<Note>
  Not all Cards work with every type of Node. The Card tray will only display Cards that are compatible with the Node you've selected.
</Note>

<Tip>
  When you install an integration, its Cards will become available in the Card tray. Check out the [integrations documentation](/docs/integrations/get-started/introduction) for more information on integration-specific Cards.
</Tip>

## Configure a Card

You can access a Card's configuration options by selecting the Card after adding it to your Workflow. This will open the Card's inspector in the Studio's right panel:

<Frame>
  <img alt="Card inspector" />

  <img alt="Card inspector" />
</Frame>

The Card's configuration fields could be either mandatory or optional—mandatory fields are marked with <span>\*</span>.

<Note>
  If no Card is selected, Studio's right panel displays the [Emulator](/docs/studio/concepts/emulator). When a Card is selected, you can toggle between the **Inspector** and the **Emulator** tabs.
</Note>


# Send Messages
Source: https://botpress.com/docs/studio/concepts/cards/send-messages



The Send Message Card lets you **send a specific message to the user**.

<Note>
  The Send Message Card is only available for [Standard Nodes](/docs/studio/concepts/nodes/introduction#standard-node).
</Note>

## Configuration

Here's a breakdown of each Send Message Card:

### Text

Sends a piece of text to your user. The **Message to send** field is mandatory and supports standard Markdown and variables.

### Image

Sends an image to your user. The **Title** field is mandatory.

### Audio

Sends an uploaded audio file to your user. The **Title** field is mandatory.

### Video

Sends an uploaded video file to your user. The **Title** field is mandatory.

### File

Sends a file to your user. The **Title** field is mandatory.

### Card

Pairs an uploaded image with a title, subtitle, and action button, like a link to a website. The **Title** and **Image** fields are both mandatory.

### Carousel

Groups multiple cards into a scrollable carousel.

### Location

Sends an address to your user. The **Latitude** and **Longitude** fields are mandatory.


# Set inactivity timeout
Source: https://botpress.com/docs/studio/concepts/cards/set-inactivity-timeout



You can use the Set Inactivity Timeout Card to **override the default inactivity timeout** configured in your [Bot Settings](/docs/studio/concepts/bot-settings#inactivity-timeout).

<Tip>
  This Card won't work in the Studio's Emulator. Instead, you can test it using the [shareable Webchat link](/docs/get-started/quick-start#preview-and-share-your-bot).
</Tip>

## Configuration

<Note>
  This Card is only available for [Standard Nodes](/docs/studio/concepts/nodes/introduction).
</Note>

To use the Card, just [add it to any Node in your Workflow](/docs/studio/concepts/cards/introduction#add-a-card). The new inactivity timeout will apply starting from when the Card executes.

It has the following settings:

* **Conversation ID**: The ID of the conversation to update. Defaults to [`event.conversationId`](/docs/studio/guides/advanced/event-properties#param-conversation-id) (current conversation)
* **Timeout**: The duration of the timeout in minutes. Set to `0` for the conversation to never expire, or to `-1` to reset to the default timeout


# Tables
Source: https://botpress.com/docs/studio/concepts/cards/tables



You can use table Cards to perform operations on data you have stored in a table. This page contains a list of available table Cards.

<Note>
  Table cards don't directly display their result. You'll need to first save the data in variables to be able to use them in the conversation.
</Note>

## Get Record

To retrieve a specific record from a table, use the **Get Record** Card. For example, you might use the Get Record operation to retrieve a user's profile information based on their unique user ID. Here's how to do it:

1. Add the **Get Record** Card to the desired Node.
2. Select the table you want to get the record from.
3. Select the **Record ID** you want to retrieve. You can either select a default ID or use variables.
4. Choose the result variable that will store the record data. (This variable needs be an [Object](/docs/studio/concepts/variables/overview#data-types-for-variables) since table records are objects.)
5. Done! You can use this variable in other Cards to access the record data.

## Insert Record

To create a new record in a table, use the **Insert Record** Card. This operation can be particularly useful when you need to store new information, such as a new user's details or a newly completed transaction. Here's how to do it:

1. Add the **Insert Record** card to the desired Node.
2. Select the table where you want to insert the record.
3. Define a value for each field. You can either define a value manually or use variables.
4. Done! Once the conversation goes through this card, the record will be created in the table.

## Update Record

To update a record in a table, use the **Update Record** Card. For example, you might use this operation to update a user's profile information or to update the status of a transaction. Here's how to do it:

1. Add the **Update Record** card to the desired Node.
2. Select the table you want to update.
3. Select the **Record ID** you want to update. You can either select a default ID or use variables. For example, if you want to update a user's profile information, you can specify their user ID as the unique identifier.
4. Select **Add properties to update**, then select the columns you want to change. For each column, you can define a value manually or use variables.
5. Done! Once the conversation goes through this card, the record will be updated in the table.

## Delete Record

To delete a record in a table, use the **Delete Record** Card. For example, you might use this operation to delete a user's data if they choose to deactivate their account. Here's how to do it:

1. Add the `Delete Record` card to the desired Node.
2. Select the table where you want to delete the record.
3. Select the ID of the record you want to delete. You can either select a default ID or use variables.
4. Done! Once the conversation goes through this card, the record will be deleted from the table.

<Warning>
  Deleted records can't be recovered—make sure you're deleting the correct record.
</Warning>

## Find Records

To search for and fetch multiple records, use the **Find Records** Card. For example, you might use this operation to fetch all transactions made by a specific user. Here's how to do it:

1. Add the **Find Records** Card to the desired Node.
2. Select the table where you want to find records.
3. Define your filter criteria in natural language. You can also use variables to make this query dynamic like: `Price is below ${workflow.maxPrice}`.
4. Choose the result variable that will store the data. (This variable needs to have the [Array](/docs/studio/concepts/variables/overview#data-types-for-variables) type)
5. Done! You can use this variable in subsequent Cards to access the data.


# Utilities
Source: https://botpress.com/docs/studio/concepts/cards/utilities

Cards that provide utility in the Studio, and aren't part of your bot's Workflow.

## Comment

The Comment card allows you to add a comment to the Workflow. It's useful to explain the Workflow to other people or to add notes to yourself.

Pick the Comment Card from the Utility Cards section in the Toolbox and drop it on the Workflow, or right-click the editor to see the Comment option. Click on the card to edit the content.

You can change the text size, color and style. You can add links, pre-formatted code and bullet point lists.

## Image

The Image card allows you to add an image window to the Workflow. It prompts you to select a file from your local machine. The image can't be changed later.

## Video

The Video card allows you to add a video window to the Workflow. It accepts YouTube URLs and it's useful for adding relevant content that don't fit in notes or images. The video can't be changed later.

## Log

Logs a message to the Logs console and the Emulator for debugging purposes (similar to a console.log inside an execute code card), You can use it to print variables, messages or any other information you need to debug your Workflow.

### Log Message

The message you want to log. You can use variables and expressions.

The log message can be a simple text or a JSON object. If you use a JSON object, it will be displayed in a more readable way.

### Logging Levels

**Debug**: Use this level to log detailed information about the Workflow execution. It's useful to debug the Workflow and understand how it works.

**Info**: Use this level to log general information about the Workflow execution. It's useful to understand the Workflow behavior and the data it's processing.

**Warning**: Use this level to log warnings about the Workflow execution. It's useful to alert about potential issues or unexpected behavior.

**Error**: Use this level to log errors about the Workflow execution. It's useful to alert about critical issues that need to be fixed.


# Webchat
Source: https://botpress.com/docs/studio/concepts/cards/webchat

Cards that allow you to interact with the Webchat widget.

Webchat Cards are specialized Cards available in Botpress that enable you to directly control and interact with the Webchat widget embedded on your website. These Cards allow you to manage the behavior of the Webchat widget, handle user interactions, and customize the chat experience for your users.

Below is an overview of each category of Webchat Interaction Cards available through the card tray:

## Configure Webchat

The **Configure Webchat** Card allows you to adjust the settings of the Webchat widget dynamically. You can change visual and functional aspects of the webchat, such as modifying the color scheme, adjusting welcome messages, or toggling features like file uploads. This Card helps personalize the user experience based on the context of the conversation or user preferences.

## Send Custom Event

The **Send Custom Event** Card is used to trigger custom events in the Webchat widget, allowing you to send data from your bot to the Webchat or perform specific actions based on user interactions. This Card is particularly useful for tracking user behavior, integrating analytics, or triggering specific Workflows within the webchat.

## Get User Data

The **Get User Data** Card allows you to retrieve information about the user interacting with the Webchat widget, such as their location, browser type, or other metadata. This data can be used to tailor the conversation, provide localized responses, or make decisions based on the user’s context.

## Hide Webchat

The **Hide Webchat** Card enables you to programmatically hide the Webchat widget from the user’s view. This can be used to control when the chat is accessible, such as hiding the widget after a session ends or when a specific condition is met.

## Show Webchat

The **Show Webchat** Card allows you to display the Webchat widget to the user, ensuring the chat is visible when you want to prompt user interaction. This is useful for engaging users at specific moments in their journey, such as after a certain time on the page or following a specific action.

## Toggle Webchat

The **Toggle Webchat** Card provides the ability to switch the Webchat widget between visible and hidden states. This Card is useful when you want to allow the user to control the visibility of the chat or when creating interactive Workflows that respond to user actions dynamically.


# Keyboard Shortcuts
Source: https://botpress.com/docs/studio/concepts/controls-and-settings/keyboard-shortcuts

Studio Keyboard Shortcuts

You can use these studio shortcuts for saving your time and focusing on building better bots.

| Shortcut                                             | Windows      | Mac          |
| :--------------------------------------------------- | :----------- | :----------- |
| Copy Node                                            | ctrl+c       | cmd+c        |
| Paste Node                                           | ctrl+v       | cmd+v        |
| Delete Node                                          | del          | del          |
| Search                                               | ctrl+f       | cmd+f        |
| Toggle Left Panel <br /> (Explorer, Library, Hooks)  | ctrl+b       | cmd+b        |
| Toggle Right Panel <br /> (Inspector & Emulator)     | ctrl+e       | cmd+e        |
| Toggle Bottom Panel <br /> (Debugger & logs)         | ctrl+j       | cmd+j        |
| Message History <br /> (Emulator, previous messages) | Arrow ↑ or ↓ | Arrow ↑ or ↓ |
| Create New Session <br /> (Emulator)                 | ctrl+Enter   | ctrl+Enter   |

## Admin Dashboard Keyboard Shortcuts

| Shortcut                                               | Windows | Mac   |
| :----------------------------------------------------- | :------ | :---- |
| Access specific bots and workspaces in Admin Dashboard | ctrl+k  | cmd+k |

## Tables Keyboard Shortcuts

| Shortcut        | Windows                | Mac                    |
| :-------------- | :--------------------- | :--------------------- |
| Cell Navigation | Arrow ↑ or ↓ or ← or → | Arrow ↑ or ↓ or ← or → |
| Edit Cell       | Enter                  | Enter                  |
| Exit Edit Cell  | ESC                    | ESC                    |


# Commands
Source: https://botpress.com/docs/studio/concepts/controls-and-settings/studio-commands



Botpress makes available some commands that you can use throughout your development process. These work in production as well, to troubleshoot issues and restart conversations.

| Command       | Where to Input                                                           | When to use                                                                                                                                                         |
| :------------ | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| //state/reset | In the [Emulator](/docs/studio/concepts/emulator) or in a Channel integration | You should run this command where there's a problem with the state of your bot which could be caused by deleting nodes, Workflows or variables and other situations |


# Studio Preferences
Source: https://botpress.com/docs/studio/concepts/controls-and-settings/studio-preferences



<img />

## Workflow - Snap to Grid

The Snap to Grid feature in Botpress allows you to align nodes and connectors on the grid, making it easier to organize and visualize your bot's Workflows.

### Enabled

To enable Snap to Grid, follow these steps:

1. Open the Botpress Studio and navigate to the Botpress Icon (top-left)
2. Go to **Studio Preferences** -> Check the box -> **Workflow - Snap to Grid**.

Once Snap to Grid is enabled, the nodes and connectors will automatically align to the nearest grid lines when they're moved.

### Disabled

When the **Snap to Grid** feature is turned off, the Workflow editor allows for more free-form movement of nodes and connections. Nodes and connections can be dragged and placed anywhere on the canvas, without being automatically aligned to the grid.

This can be useful for creating more complex and visually dynamic Workflows that don't conform to a strict grid layout.

## Studio Theme

The Studio Theme feature allows you to change the color scheme of the Botpress Studio interface. This can be useful for customizing the look and feel of your bot, or for making it easier to distinguish between different bots in your workspace.

Available themes include:

1. System (default)
2. Light
3. Dark


# Copy to bot
Source: https://botpress.com/docs/studio/concepts/copy-to-bot

Duplicate the configuration of a bot into another bot.

### Use Cases

This feature is useful in couple scenarios:

**Development, Staging, and Production Environments**:

* Maintain separate bots for development, staging, and production. This allows you to experiment freely in the development bot and test changes without compromising the settings or data of your staging or production bots.

**Managing Multiple Client Bots:**

* If you maintain a single master bot and deploy multiple copies as production bots for different clients, this feature helps keep them synchronized while ensuring each remains isolated.

***

### How to Copy a Bot

1. In **Botpress Studio**, navigate to the left panel and click the **Botpress icon**.
2. Hover over **Copy to Bot** and select the bot you want to copy to (or create a new bot).
3. A confirmation dialog will appear, warning that this action will modify the target bot. Click **Confirm** to proceed.
4. The copy process will begin. Once complete, a dialog will appear with details about the updates made to the target bot.
5. From here, you can choose to open the target bot or close the dialog and continue editing the source bot.

<img />

***

### How it works

When a user requests to copy a bot to another bot, the following actions are performed:

**Workflows, Variables and Hooks are copied**

* All Workflows, variables and hooks from the source bot will be copied to the target bot.
* Existing Workflows and variables in the target bot will be overwritten.

**Integrations are synced**

* New or outdated integrations from the source bot will be installed in the target bot. These will need to be configured in the target bot’s studio.
* Existing integrations in the target bot will be preserved with their configuration.
* Integrations that exist only in the target bot will remain unchanged.

**Tables are synced**

* New tables from the source bot will be added to the target bot.
* New columns in existing tables will be added to the corresponding tables in the target bot. If there was existing data, the new column will be null for each entry.
* Deleted columns in existing tables will be removed from the target bot’s equivalent tables. If there was existing data, only the data for that column will be lost—other data remains intact.
* Tables that exist only in the target bot will remain unchanged.

**Knowledge Base (KB) Files are synced**

* New files from the source bot will be duplicated in the target bot.
* If a file is updated in the source bot, the corresponding file in the target bot will be overwritten.
* Files that exist only in the target bot will remain unchanged.


# Debugger, Logs & JSON
Source: https://botpress.com/docs/studio/concepts/debugger-logs-json



<img />

## Event Debugger

The Event Debugger provides information on how your bot understood the user's message and why it made specific decisions. It also displays the complete event payload, including NLU metadata, state, and raw responses.

To open or close the Debugger, you can use the keyboard shortcut **cmd/ctrl + j**. This will toggle the Debugger on and off and allow you to access the information it provides.

## Logs

By using logs, you can see what happened step-by-step before an error occurred. This can help you understand what went wrong and how to fix it.

It's important to include enough logging in your bot to ensure that you have enough\
information to find and fix issues. By analyzing the Botpress Logs, you can pinpoint\
exactly where the problem occurred and take the necessary steps to resolve it.

Logging in Botpress is similar to logging in JavaScript. You can use the `console.log()` function in the [Code Card](/docs/studio/concepts/cards/execute-code) to print messages to the Botpress Logs. This function takes a string as an argument and prints it to the Botpress Logs.

### Logging User Information

If you're interested in understanding what user data is being processed, you might want to log their first name. This could help you trace if the correct user data is being accessed and used in your Workflow.

**Example use-case**: Understanding which user's data is being processed especially if your bot offers personalized experiences.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
console.log("User's First Name:", user.firstName);
```

### Logging Workflow Data

You might want to know which phone number is being used in a specific Workflow. By logging this, you can ensure that the correct numbers are being pulled from your database or user input.

**Example use-case**: Debugging Workflows that might involve sending SMS messages or making phone calls. Ensuring that the correct phone numbers are used can be critical.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
console.log("Workflow Phone Number:", workflow.phoneNumber);
```

### Logging Environment Configurations

If your bot accesses external APIs or databases, the API key or endpoint might change depending on the environment (development, staging, production, etc.). Logging the `env` variables can help ensure that the bot is using the correct configurations.

**Example use-case**: Troubleshooting connectivity or access issues with external services. By logging the API key or endpoint, you can ensure you're using the correct configurations and not accidentally hitting a production database during development or vice versa.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
console.log("Current API Key:", env.apiKey);
```

### Checking the Botpress Studio Logs

To check the Botpress Studio Logs, open up the bottom panel and click on the **Logs** tab. This will display all the logs that have been generated by your bot.

<Note>
  Note

  The logs are displayed in reverse chronological order, with the most recent log at the top. You can click on a log to expand it and view its details.
</Note>

### Checking the Production Logs

To check the [Production Logs](/docs/get-started/manage-your-agent/inspect#logs) (or logs from a deployed bot), go to the admin dashboard -> select your workspace and bot -> click on the **Logs** tab. This will display all the logs that have been generated by your deployed bot.

## State

In a bot conversation, each session has an associated state which is created at the beginning of the conversation just before the Entry Node is processed. The state persists throughout the conversation and is used to keep track of information related to the ongoing interaction with the user.

The state is global to the conversation, which means that if the conversation spans multiple Workflows, all the Workflows will share the same state. This allows information to be passed between Workflows and ensures that the bot has a consistent view of the conversation history.

The state can be used to store variables, such as the user's name, preferences, or history of interactions, that are needed throughout the conversation. It can also be used to keep track of the bot's progress through the conversation, such as which questions have been asked and which tasks have been completed.

By using the state effectively, you can create more personalized and engaging bot experiences for your users.

## JSON

This tab displays the raw information that's processed during each conversation exchange in the Botpress Emulator. The information can be accessed through **event.property**, where "property" refers to one of the properties listed in the table below.

Here is a table that describes each property in detail:

| Property       | Description                                                                                                                                                                      |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Type           | A string property that indicates the type of the message (text, audio, video, etc.)                                                                                              |
| Channel        | A string property that specifies the channel or platform through which the message was received. For example, the channel can be an emulator, Facebook Messenger, WhatsApp, etc. |
| Direction      | A string property that specifies the direction of the message-whether the message is incoming or outgoing.                                                                       |
| Payload        | A JSON object that encapsulates the message data. The structure of the payload object depends on the type of message.                                                            |
| UserId         | A string property that identifies the user who sent the message.                                                                                                                 |
| BotId          | A string property that identifies the bot or conversational AI system that received the message.                                                                                 |
| CreatedOn      | A timestamp that specifies the date and time when the message was received.                                                                                                      |
| ConversationId | A string property that identifies the conversation thread to which the message belongs.                                                                                          |
| ID             | A unique identifier for the message.                                                                                                                                             |
| Preview        | A preview or summary of the message.                                                                                                                                             |
| MessageId      | A string property that identifies the ID of the message.                                                                                                                         |
| Tags           | An object that contains tags associated with the message.                                                                                                                        |
| Flags          | An object that contains flags associated with the message.                                                                                                                       |
| State          | An object that contains the state of the conversation.                                                                                                                           |
| Suggestions    | An array of suggested responses or actions that the bot can take based on the message.                                                                                           |
| NLU            | An object that encapsulates the results of the natural language understanding (NLU) process for the message.                                                                     |
| Decision       | An object that encapsulates the decision-making process for the message.                                                                                                         |


# Emulator
Source: https://botpress.com/docs/studio/concepts/emulator



You can debug your bot conversation using the built-in Emulator in the right-side panel.

<Note>
  Note

  To visualize the actual user experience, use the Share button to have a hosted easily shareable version of the [Web Chat](/docs/webchat/get-started/introduction) (this is the production bot already, conversations will be saved) or ideally test the bot in the channel you intend to deploy it on. Conversations in the Emulator won't be saved and the [bot invocations](/docs/get-started/configure-your-workspace#track-usage-quotas) won't be counted against your usage quota, but AI operations will.
</Note>

## Shortcuts

### Accessing the Emulator

Press `cmd/ctrl + e` to toggle the Emulator open or closed.

### Resend the Same Messages

Pressing ↑ or ↓ on your keyboard in the text input allows you to navigate and resend previously sent messages quickly.

<Info>
  Info

  The last 20 messages sent are persistently stored in your browser storage.
</Info>

## Options

### New Conversation

The `New Conversation` button erases the history and state from the old conversation and start a new conversation with the same user information. It's available at the top right corner of the emulator.

### Start as a new user

The `Start as new user` button erases the history and state from the old conversation and start a new conversation with different user information. It's available at the top right corner of the emulator behind the 3 dots.

### Simulate timeout event

The `Simulate timeout event` button triggers the [Timeout Workflow](/docs/studio/concepts/workflows#timeout) so you can check how the bot behaves when the conversation expires. It's available at the top right corner of the emulator behind the 3 dots.

## In-line Logs

The Emulator shows the status of the conversation and the different steps that are being or have been executed under the hood to get the bot's response. They're a simpler version of the [Event Debugger](/docs/studio/concepts/debugger-logs-json)'s summary. Bot events, and card-processing results are shown this way, only in the emulator.

### Bot events

* Conversation started: The user has started the conversation by sending a message or a [Trigger](/docs/studio/concepts/triggers) has fired.
* Conversation ended: The conversation flowed to an End node and has gone through the [Conversation End Workflow](/docs/studio/concepts/workflows#conversation-end), or it has ended by not having possible transitions.
* Error occurred: An irrecoverable error has occurred and the conversation has flowed to the [Error](/docs/studio/concepts/workflows#error) . The error message is visible by hovering the status.
* Waiting for user input: The bot is waiting for the user to send a message in order to proceed with the conversation.

### Knowledge Base

* Answer found in Knowledge Base: The bot has gone through the [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) and found an answer to the user's question. Clicking it will take you to the [Logs tab](/docs/studio/concepts/debugger-logs-json) where you can see in details what was sent to the AI and the raw output.
* Knowledge disabled on that node: The bot won't try to find an answer in the Knowledge Base because this node doesn't expect or accept Knowledge questions.
* No content matched the query: There is no content in the Knowledge Base that matches the user message. May accompany the previous status.
* Knowledge Base answer: Text displayed automatically after a question without the need of a Text card. It will contain the citations to help you [debug the answers](/docs/studio/concepts/knowledge-base/introduction#debugging).

### Execute

* Executing code: The bot is executing some custom code from an [Execute Code card](/docs/studio/concepts/cards/execute-code).
* Executed code: The bot has finished executing the code. It's mentioned how many milliseconds it took to run.

### AI

* AI Task Running: The bot is running an AI Task. This involves making a request to the selected LLM model, getting a response and then processing it.
* AI Task Completed: The bot has finished running the AI Task. It's mentioned how many milliseconds it took to run.

### Flow Logic

* Entered Workflow - The conversation has flowed to a different Workflow. The Workflow name is mentioned.
* Transitioned: The conversation has flowed to another Workflow or node. It's mentioned the name of the Workflow and the node it transitioned to. Clicking it will lead you to the exact node.
* Restarting from node: The conversation is being restarted from a specific node by user request. It's mentioned the name of the node it's restarting from.

### Capture Information

* Capturing Variable: The bot is currently trying to extract information from the user message with a [Capture card](/docs/studio/concepts/cards/capture-information) to optionally save it in a [variable](/docs/studio/concepts/variables).
* Captured variable: The bot has successfully extracted information from the user message and saved it in a variable.
* Capture variable failed: The bot wasn't able to extract information and has reached the limit of [retries](/docs/studio/concepts/cards/capture-information#retries).


# Find
Source: https://botpress.com/docs/studio/concepts/find

Quickly search through your bot's content, Workflows, and configurations.

The Find function in Botpress Studio is a powerful tool that helps you quickly search through your bot’s content, Workflows, and configurations. It allows you to locate specific elements, such as nodes, actions, text, or variables, within your bot project, making it easier to navigate and edit complex bots.

## Features

* **Quick Search:** Instantly locate items like specific nodes, cards. actions, intents, or text within your Workflows and content.
* **Contextual Results:** Provides contextual search results, showing where the found items are located within the bot’s structure.
* **Navigation:** Click on a search result to jump directly to that element within the Botpress Studio.
* **Keyword Highlighting:** Highlights occurrences of your search term in the Workflows, helping you see exactly where changes are needed.


# Home
Source: https://botpress.com/docs/studio/concepts/home

Main menu with global configuration for your bot.

The <Icon icon="house" /> **Home** page is Botpress Studio's main menu. It displays general information about your bot and allows you to configure some global settings.

Most of the options on the **Home** page are shortcuts to configure your main Workflow's [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node). If you don't use an Autonomous Node, you can still configure your bot's [communication channels](#communication-channels) or view a [detailed analysis of your bot's conversations](#conversation-analysis).

## Instructions

<Note>
  The **Instructions** field is only available if you have an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) in your bot's main Workflow.
</Note>

You can define a global prompt for your bot in the **Instructions** field. This prompt influences how the bot interprets and responds to user input by giving it a specific context or role to operate within:

<Frame>
  <img alt="Instructions" />

  <img alt="Instructions" />
</Frame>

The **Instructions** field directly maps to the **Instructions** for your main Workflow's Autonomous Node. When you update one, the other will also update:

<Frame>
  <img alt="Instructions for Autonomous Node" />

  <img alt="Instructions for Autonomous Node" />
</Frame>

## Knowledge Bases

<Note>
  The **Knowledge Base** section is only available if you have an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) in your bot's main Workflow.
</Note>

You can add [Knowledge Bases](/docs/studio/concepts/knowledge-base/) to give your bot sources it can reference when answering questions:

<Frame>
  <img alt="Knowledge Bases" />

  <img alt="Knowledge Bases" />
</Frame>

These sources can include documents, websites, tables, and other forms of structured (or unstructured) data. When you add Knowledge Bases, this section will display a summary of them.

## Tools

<Note>
  The **Tools** section is only available if you have an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) in your bot's main Workflow.
</Note>

You can use the **Tools** section to quickly add resources and actions your bot can use:

<Frame>
  <img alt="Tools" />

  <img alt="Tools" />
</Frame>

The **Tools** section directly maps to the Cards in your main Workflow's Autonomous Node. When you update one, the other will also update:

<Frame>
  <img alt="Autonomous Node Cards" />

  <img alt="Autonomous Node Cards" />
</Frame>

## Communication Channels

<Tip>
  For detailed guides on setting up different channels, check out the [Integrations documentation](/docs/integrations/).
</Tip>

You can deploy your bot in different channels  the **Communication Channels** section:

<Frame>
  <img alt="Communication Channels" />

  <img alt="Communication Channels" />
</Frame>

## Conversation analysis

You can view a summary of your bot's conversations in the **Conversation Analysis** section. This includes sentiment analysis, summaries of conversation topics, and insights into whether users' questions were resolved.

## Learning Experiences

<Note>
  The **Learning Experiences** section is only available if you have an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) in your bot's main Workflow.
</Note>

You can provide feedback on your bot's responses in the [Emulator](/docs/studio/concepts/emulator). Then, you can view a summary of your feedback in the **Learning Experiences** section:

<Frame>
  <img alt="Learning experiences" />

  <img alt="Learning experiences" />
</Frame>


# Hooks
Source: https://botpress.com/docs/studio/concepts/hooks



Hooks **execute custom JavaScript code** at specific cycles of your bot's operation. For example:

* [Before each outgoing message](#before-outgoing)
* [After each LLMz iteration](#after-llmz-iteration)
* [At the end of each conversation](#after-conversation-end)

You can use Hooks to intercept and modify messages, perform logging, integrate with external systems, and more.

<Tip>
  ### Hooks vs. Actions / Execute Code

  Hooks let you use custom code with your bot, just like [Actions](/docs/studio/concepts/actions) and [Execute Code Cards](/docs/studio/concepts/cards/execute-code). The key difference is when the code runs:

  * Actions and Execute Code Cards run at some point in your [Workflow](/docs/studio/concepts/workflows).
  * Hooks run during specific stages of the bot’s operation cycle
</Tip>

## Overview

When you add a new Hook, it defines a [function](https://www.w3schools.com/js/js_functions.asp) that executes every time your bot reaches a certain cycle of its operation.

All Hooks take an `event` parameter, which contains information about the event that triggered the Hook.

<Note>
  Some Hook types take additional parameters—check out the Hook guides on this page for more information.
</Note>

### Add a Hook

1. Navigate to the <Icon icon="anchor" /> Hooks section in the Studio's left navigation bar.
2. Select **Create Hook**, then choose a type for the Hook.
3. Choose a name for the Hook. Done!

***

## Hook types

Here's a breakdown of each type of Hook:

### Before Incoming

This Hook type executes its code before your bot processes an incoming `event`.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

### After Incoming

This Hook type executes its code after the incoming message has been processed, but before the bot has responded.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

### Before Outgoing

This Hook type executes its code before the bot's reply is sent to the user.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="outgoingEvent" type="IO.OutgoingEvent">
  The message sent by the bot
</ResponseField>

### Before LLMz Execution

This Hook type executes its code before the LLMz engine begins its execution.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="LLMZ.CreateContext">
  The current context provided to the LLMz

  <Expandable>
    <ResponseField name="id" type="string">
      The unique identifier of the LLMz execution, prefixed with `llmz_`
    </ResponseField>

    <ResponseField name="version" type="any">
      The version of the LLMz engine or context
    </ResponseField>

    <ResponseField name="instructions" type="string">
      Optional instructions provided to guide the LLMz execution
    </ResponseField>

    <ResponseField name="objects" type="LLMZ.Obj[]">
      A list of objects relevant to the LLMz context
    </ResponseField>

    <ResponseField name="tools" type="LLMZ.Tool[]">
      A list of tools available for the LLMz engine to use
    </ResponseField>

    <ResponseField name="loop" type="number">
      The current loop count of the LLMz iteration process
    </ResponseField>

    <ResponseField name="temperature" type="number">
      The temperature setting used for the LLM model
    </ResponseField>

    <ResponseField name="model" type="string">
      The name or identifier of the LLM model being used.
    </ResponseField>

    <ResponseField name="transcript" type="OAI.Message[]">
      The conversation transcript, including all prior messages in the current context
    </ResponseField>

    <ResponseField name="location" type="LLMZ.Location">
      The current location within the bot's logic
    </ResponseField>
  </Expandable>
</ResponseField>

### After LLMz Execution

This Hook type executes its code after the LLMz engine finishes its execution.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="execution" type="LLMZ.ExecutionResult">
  The result of the execution
</ResponseField>

### After LLMz iteration

Depending on how demanding the task is, the LLMz may loop through multiple iterations before finishing its execution. This Hook type executes its code after each iteration.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="iteration" type="LLMZ.IterationResult">
  The result of the iteration
</ResponseField>

### After Conversation End

This Hook type executes after the conversation has **explicitly ended** (transitioned to an [End Node](/docs/studio/concepts/nodes/introduction#end-node))

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

### After Turn End

This Hook type executes after a full turn has completed—meaning the bot has received user input, processed it, and responded.

You can use a Hook of this type to [track AI spend and token cost](/docs/studio/guides/how-to/track-ai-spend-in-table/) for your bot.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="IO.TurnMetadata">
  The turn's metadata

  <Expandable>
    <ResponseField name="tokens" type="IO.TokenReport">
      The token information and cost for the current turn

      <Expandable>
        <ResponseField name="summary" type="string">
          A summary of the token usage for the last turn
        </ResponseField>

        <ResponseField name="details" type="string">
          A detailed breakdown of token usage for the last turn
        </ResponseField>

        <ResponseField name="billedTokens" type="number">
          The number of billed tokens during the last turn
        </ResponseField>

        <ResponseField name="usages" type="IO.TokenUsage[]">
          An array of token usages

          <Expandable>
            <ResponseField name="count" type="number">
              The number of tokens in the usage
            </ResponseField>

            <ResponseField name="spend" type="number">
              The AI spend for the usage (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000.
            </ResponseField>

            <ResponseField name="duration" type="number">
              The duration (in milliseconds) of the usage
            </ResponseField>

            <ResponseField name="location" type="string">
              The location in the Workflow where the usage occurred
            </ResponseField>

            <ResponseField name="cached" type="boolean">
              Whether the usage was cached
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="totalTokens" type="number">
          The total number of tokens used in the last turn
        </ResponseField>

        <ResponseField name="billedTokens" type="number">
          The total number of billed tokens used in the last turn
        </ResponseField>

        <ResponseField name="cost" type="number">
          The AI spend for the last turn (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000.
        </ResponseField>

        <ResponseField name="savingsPercent" type="number">
          The percentage of savings on AI spend for this turn.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Troubleshooting

If your Hook isn't behaving as expected, you can [check your bot's logs](/docs/studio/concepts/debugger-logs-json) to diagnose any problems.


# Import & Export
Source: https://botpress.com/docs/studio/concepts/import-export-bots



You may want to import or export a bot for various reasons, such as:

* Sharing the bot with others - friends, clients, etc.
* Contributing the bot to the community
* Seeking help to fix issues
* Creating a backup of the bot
* Transferring the bot to a different workspace or account

And with Botpress Cloud, you can do that with just a few clicks!

## How to Export a Bot

On the left panel in your Botpress Studio, click the Botpress icon and select Import / Export. Then click Export as.

Studio will start preparing the export, which may take some time, depending on the amount of content in your tables and knowledge bases. When it's done, the download will start automatically.

<Info>
  Info

  Bots \~3gb or larger **can't** be exported!
</Info>

The exported file will be a `.bpz` file (which is a special archive format for Botpress Cloud bots). It will have the name of your bot and the current date (for example: recipe-bot - 2023 Sep 06.bpz).

<Warning>
  Warning

  Don't attempt to extract the file or modify its content; otherwise, you may not be able to import your bot again!
</Warning>

The exported file contains your whole bot, including:

* Bot information and settings
* Agents settings
* Knowledge bases - with sources (files are stored on our servers and only linked in the export to keep it small)
* Tables - with records
* Intents and entities
* Hooks
* Variables (Workflow, user, bot, configuration) - names and default values
* Folders
* Workflows and nodes
* Cards - with content
* Transition lines

So you can rest assured that all of your data is included!

## How to Import a Bot

<Warning>
  Warning

  Importing a bot will overwrite the current bot, including media, knowledge bases, documents and tables. Proceed with caution!
</Warning>

On the left panel in your Botpress Studio, click the Botpress icon and select Import / Export. Then click Import. Next, click "Select bot archive to upload" and the explorer window will open. Find the `.bpz` file you want to import on your computer and click Open.

You have now successfully imported your bot! Test it using the Emulator or publish it to make it available to your users.

<Tip>
  Good to know

  You can import bots up to 120 MB!
</Tip>

<Note>
  Restoring the Integrations

  Remember to set up the desired integrations again in the Dashboard, so that it works on the channels exactly as it did before you exported it!
</Note>

## Video tutorial

<YouTube />


# Integrations
Source: https://botpress.com/docs/studio/concepts/integrations

Allow your bot to connect to external services, APIs, and tools.

Integrations extend the capabilities of your bots by connecting them with external services, APIs, and tools. They allow your bots to fetch data, trigger actions, interact with third-party platforms, and provide more dynamic and powerful user experiences. They can send and receive data from other tools, or they can be used to deploy your bot on alternative messaging channels.

## Using Integrations

### Search

To find integrations, navigate to the integrations icon in the left-hand menu of the Studio, indicated by a puzzle icon.

You can search for integrations to third-party services by name here, like WhatsApp or Messenger.

### Install

Clicking on an integration from a search result will open a menu that allows you to install that integration to your bot. From this menu, you can also see information like prerequisites, installation instructions, and the Botpress user responsible for contributing the integration to the hub.

<Check>
  Verification

  Integrations with a checkmark icon next to the name have been verified and confirmed as trusted integrations for safety and function by the Botpress team.
</Check>

### Configure

Once you've installed an integration to your bot, you can proceed with any necessary configuration steps. This can include providing API keys, inputting data, or completing third-party setup wizards.

### Usage

Once you've installed and configured an integration to your bot, you can start using it.

For integrations that deploy your bot to a messaging channel like WhatsApp or Telegram, after you've configured the integration and published your bot, it will start sending and receiving messages on those channels.

For integrations that enhance your bot's functionalities, like connecting to a third-party tool, you will find additional cards in the Card Tray that enable certain integration actions. Refer to the documentation for the integration you are using for detailed instructions.


# Add sources to Knowledge Base
Source: https://botpress.com/docs/studio/concepts/knowledge-base/add-sources



You can add sources to a Knowledge Base—your bot will reference them when searching for an answer to a user's question.

***

## Websites

To add a website to your Knowledge Base, select **Website** in its menu. Here's a breakdown of the options for adding websites:

### From a website's root domain

By default, you can add a root domain (or some subpath of a root domain) and let Botpress discover the other pages on that website.

For example, if you enter `botpress.com`, Botpress will discoverer all the subpaths of that domain, like:

* `botpress.com/docs`
* `botpress.com/features/knowledge-bases`
* `botpress.com/industries/ecommerce`

and more. Then, you can select which pages to add to your Knowledge Base.

### From specific pages

If you want to add specific web pages without discovering any subpaths, open the drop-down menu and select **Specific Web Pages**. Then, enter the exact address of the page you want to add.

For example, if you enter `botpress.com/blog`. you'll add that exact page only—none of its subpaths will be included.

### Re-crawling

By default, Botpress indexes any web pages you add once, then continues to reference that version of the pages. However, you can also schedule a re-crawling of the pages:

1. After adding web pages to your Knowledge Base, select them from your list of knowledge sources.
2. Open the **Recrawl** drop-down menu.
3. Select one of the other re-crawling schedules—like **Recrawl Daily**.

Re-crawling is useful for keeping your bot up to date on changes to your website. For example, the Botpress documentation's
<a>AI assistant</a>
re-crawls `botpress.com/docs` every day to stay up-to-date when new documentation is added.

***

## Documents

You can upload documents and files to your Knowledge Base—just select the **Documents** option from its menu. Here's a list of supported file formats:

* `.pdf`
* `.html`
* `.txt`
* `.doc`
* `.docx`
* `.md`

<Note>
  Documents can be up to 50 MB each.
</Note>

### From API

Knowledge Bases use the Botpress [Files API](/docs/api-reference/files-api/getting-started) to manage documents. This means you can programmatically upload documents to a Knowledge Base:

1. Select the **API** option from your Knowledge Base's menu.
2. Follow the on-screen instructions.

***

## Tables

If you use [tables](/docs/studio/concepts/tables) to store data, you can connect them to a Knowledge Base.

1. Open the Knowledge Base.
2. Select the **Table** option.
3. Select any tables you'd like to add.

After adding a table to your Knowledge Base, users can ask natural-language questions about the data in your tables—this is useful for inventory data, pricing charts, and other types of structured data.

***

## Search the web

You can give your bot the ability to search the web independently for answers to user questions—just select **Web Search** from your Knowledge Base's menu.

While [adding websites](#add-websites) indexes data from specific web pages for your bot to reference, the **Web Search** searches the internet in real time to find an answer to the user's prompt.

By default, this option gives your bot access to search the entire web. However, you can also filter the results:

### Filter by website

You can filter which websites your bot searches on. Under **On which websites should we search on**, open the drop-down menu :

* **Search on specific websites**: Useful for scoping responses to specific sources, like a company website.
* **Search the entire web**: Useful when your bot needs access to a broader set of information to answer user questions.
* **The entire web, except these websites**: Useful for filtering out unreliable sources or competitors' websites

### Filter by time period

You can filter search results by time period. Under **Filter search results by time period**, open the drop-down menu:

* **Don't filter based on time**
* **Pages discovered in the last 24 hours**
* **Pages discovered in the last 7 days**
* **Pages discovered in the last 30 days**

When you select one of these options, it'll only include pages that Botpress indexed or discovered in the specified range.

***

## Rich text

You can add rich text directly into a Knowledge Base.

1. Open the Knowledge Base.
2. Select the **Rich Text** option.

By default, this adds an empty rich text document—you can then open and edit its contents.

### Filter by column

By default, all your table's columns are available in the Knowledge Base. If you want to filter results to only specific columns, select the table and uncheck any columns you want to exclude.

<Note>
  If your table is displaying **No searchable columns**, make sure your table has at least one column [marked as searchable](/docs/studio/concepts/tables#making-fields-searchable).
</Note>

You can connect your tables of data to a Knowledge Base, allowing users to directly search for information. This can be especially invaluable for vast datasets, as it provides a straightforward and user-friendly method to retrieve data.

***

## Sources from integrations

You can add content from certain [integrations](/docs/integrations/get-started/introduction) to your Knowledge Base. If you install an integration that's compatible with Knowledge Bases, that integration will either:

* Be displayed alongside the other options in your Knowledge Base (like the [Notion](https://botpress.com/integrations/notion) integration)
* Have [Cards](/docs/studio/concepts/cards/introduction) that handle synchronization with Knowledge Bases (like the [Google Drive](https://botpress.com/integrations/googledrive) integration)


# Knowledge Bases
Source: https://botpress.com/docs/studio/concepts/knowledge-base/introduction



<Icon icon="book-open" /> Knowledge Bases are **sources of information you provide to your bot**.

<Frame>
  <img alt="Knowledge Base" />

  <img alt="Knowledge Base" />
</Frame>

You can use a Knowledge Base to make your bot reference a specific source when answering a user. For example, you might want to:

* Provide your bot with specialized information (like company policies, pricing charts, or troubleshooting steps)
* Scope your bot's responses to specific topics
* Let your bot reference data from [tables](/docs/studio/concepts/tables) in its responses

***

## Create a Knowledge Base

To create a Knowledge Base:

1. Navigate to the <Icon icon="book-open" /> **Knowledge Base** menu in the studio.
2. Select **New Knowledge Base**.

***

## Add sources

Once you've created a Knowledge Base, you can [add sources to it](/docs/studio/concepts/knowledge-base/add-sources):

<CardGroup>
  <Card title="Websites" icon="app-window" href="/studio/concepts/knowledge-base/add-sources#websites" />

  <Card title="Documents" icon="file-text" href="/studio/concepts/knowledge-base/add-sources#documents" />

  <Card title="Tables" icon="table" href="/studio/concepts/knowledge-base/add-sources#tables" />

  <Card title="Search the web" icon="search" href="/studio/concepts/knowledge-base/add-sources#search-the-web" />

  <Card title="Rich text" icon="type" href="/studio/concepts/knowledge-base/add-sources#rich-text" />

  <Card title="Integrations" icon="boxes" href="/studio/concepts/knowledge-base/add-sources#sources-from-integrations" />
</CardGroup>

Your bot will reference these sources when searching for an answer to a user's question.

***

## Search a Knowledge Base

Your bot searches Knowledge Bases differently depending on whether it's executing an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) or a [Standard Node](/docs/studio/concepts/nodes/introduction#standard-nodes):

### Using an Autonomous Node

<Tip>
  Since your bot only references Knowledge Bases when they're needed, they're useful for de-cluttering your [Autonomous Node's prompt](/docs/studio/concepts/nodes/autonomous-node#be-specific).
</Tip>

The default Autonomous Node in a bot's [Main Workflow](/docs/studio/concepts/workflows) contains a **Search Knowledge** Card that searches all Knowledge Bases by default. This means that a newly created AI agent is already equipped to search your Knowledge Bases.

You can scope which Knowledge Bases the Autonomous Node searches using the Search Knowledge Card's configuration menu:

1. Open the drop-down menu under **Included Knowledge Bases**.
2. Select whichever Knowledge Bases you want to include in searches.

<Note>
  Depending on your needs, you can also add multiple Search Knowledge Cards to your Autonomous Node. For more information, check out the guide on [searching multiple Knowledge Bases](#search-multiple-knowledge-bases).
</Note>

### Using a Standard Node

Since Standard Nodes don't use AI to generate responses, they don't consult your Knowledge Bases by default. To make your bot search your Knowledge Bases within a Standard Node, you can use:

* A [Capture Information Card](/docs/studio/concepts/cards/capture-information#raw-input)
* A **Query Knowledge Bases** Card

<Warning>
  Both of these Cards require the [Knowledge Agent](/docs/studio/concepts/agents/knowledge-agent) to work properly—make sure it's enabled.
</Warning>

<Note>
  By default, neither of these Cards send their response to the user directly—instead, you can access the response by referencing `turn.KnowledgeAgent.answer`, then send it to the user manually.
</Note>

***

## Search multiple Knowledge Bases

If you're using an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node), you have two options for searching multiple Knowledge Bases:

### Search all Knowledge Bases simultaneously

If you need your bot to search all selected Knowledge Bases for every user query, you can use a single Search Knowledge Card:

1. [Add a Search Knowledge Card](/docs/studio/concepts/cards/introduction#add-a-card) to your Autonomous Node (if it doesn't already contain one).
2. Select the Card to open its configuration menu.
3. Open the drop-down menu under **Included Knowledge Bases**.
4. Select whichever Knowledge Bases you want to include in searches.

With this configuration, the Autonomous Node performs a search on all the selected Knowledge Bases simultaneously, then orders the results by score. This is useful if:

* You have multiple Knowledge Bases that can answer similar questions
* You need to combine the answers from different Knowledge Bases in the same message

<Warning>
  Generally, searching all Knowledge Bases simultaneously consumes more LLM tokens and has higher latency than  [picking which Knowledge Bases to search based on context](#pick-knowledge-bases-to-search-based-on-the-query).
</Warning>

### Pick Knowledge Bases to search based on the query

If you need your bot to search certain Knowledge Bases in certain circumstances, you can use multiple Search Knowledge Cards:

1. [Add multiple Search Knowledge Cards](/docs/studio/concepts/cards/introduction#add-a-card) to your Autonomous Node.
2. Configure each Card's **Included Knowledge Bases** depending on your needs.

With this configuration, the Autonomous Node views each Search Knowledge Card as a different tool, and picks one to search based on the user's query. This is useful if you have distinct Knowledge Bases that you need to query in different circumstances, and want to avoid overlap between them.

<Warning>
  For this configuration to work, you need to specify instructions in each Search Knowledge Card's **Instructions** field. Otherwise, the Autonomous Node won't be able to tell the two Cards apart, and will pick one randomly.

  For example, you could add these instructions for questions about company policies:

  <Frame>
    <img alt="Example instructions for company policy search" />

    <img alt="Example instructions for company policy search" />
  </Frame>

  And these instructions for questions about pricing:

  <Frame>
    <img alt="Example instructions for pricing search" />

    <img alt="Example instructions for pricing search" />
  </Frame>
</Warning>

***

## Handle no answer found

If your Workflow has an Autonomous Node, your bot will generate an appropriate response when it doesn't find an answer in the Knowledge Base. However, you can also program a custom response:

1. In your Autonomous Node, add a [Transition](/docs/studio/concepts/cards/flow-logic#transition) Card.
2. In the Card's **Condition** field, paste the following:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{{!event.state.agentVariables.KnowledgeAgent.turn.answer}}
```

3. Add the following to your Autonomous Node's prompt:

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Transition when no answer is found in the Knowledge Base.
```

Now, your bot will activate the Transition Card whenever it doesn't find an answer in the Knowledge Base. You can handle the transition however you want—for example, with a Node that sends a custom error message.

***

## Storage limit

Information you store in Knowledge Bases counts towards your [Vector DB Storage](/docs/get-started/configure-your-workspace#vector-db-storage), which depends on your [Botpress plan/add-ons](https://botpress.com/pricing).

***

## Troubleshooting

If your bot isn't returning the expected results, you can try troubleshooting it in a few different ways:

### Check logs

Your bot's [logs](/docs/studio/concepts/debugger-logs-json#logs) display:

* The exact query that was sent to the Knowledge Base
* The results (including source name, content preview, amount of tokens used by the content, row metadata if the source is a table) if there are any matches

Using that information, you can try refining what's sent to the Knowledge Base (or the sources themselves).

### Inspect responses

If you're using an Autonomous Node to search Knowledge Bases, you can use the [Inspect](/docs/studio/concepts/nodes/autonomous-node#check-the-inspect-window) window to analyze your bot's process when searching Knowledge Bases.


# Knowledge Base Best Practices
Source: https://botpress.com/docs/studio/concepts/knowledge-base/knowledge-base-best-practices

Set up Knowledge Bases effectively by prioritizing structured data, ensuring data quality, and using automated ingestion tools.

The efficiency of your agent relies heavily on the quality of the data fed into the Knowledge Base. Here are some best practices to follow when setting up your Knowledge Base:

## Structured vs. Unstructured Information

The success of your bot depends on how well the information in your KB is structured:

Structured Data refers to any kind of information that requires associating two or more records. For example, a Table that contains information about User emails, IDs, and products would be considered structured data.

Unstructured Data refers to any kind of information that doesn't associate multiple records. For example, this might include files like call transcripts, meeting notes, or product descriptions.

## Data Quality

The quality of the data you feed into the KB directly impacts the quality of your agent's responses. Ensure the information is accurate, up-to-date, and free of unnecessary or redundant details.

Poor-quality data will lead to poor agent performance. When planning an AI Agent project that requires KB ingestion, consider doing a redundant, obsolete, or trivial (ROT) analysis of the KB source.

Good-quality data also includes organized data. For example, if you're answering questions about multiple knowledge products, consider separating them into separate KBs, and segregate your agent's access to each KB based on the context of the conversation.

## Choosing the Right Knowledge Type

When populating your KB, use the correct type based on the nature of your information.

For instance, **Tables** are best suited for structured data. If your information can be classified by attributes or specific fields, using Tables will make it easier for your agent to search and extract data.

Use **Rich Text** for unstructured but logically organized content. It’s a great solution when Tables aren’t feasible.

Use **Documents** when your data can’t be easily represented as structured or plain text. Keep in mind that when documents are uploaded, any native styling or images is removed, and the file is converted to markdown in order to be read by an LLM.

## Using Website Crawlers and Search Engines

Botpress offers flexible options for ingesting website data into the KB:

### If you have a valid sitemap

If your website has a valid sitemap, use the Website crawler, which ingests information more effectively. Consider using a sitemap finder and/or validator to verify your sitemap's validity for this purpose.

### If you don't have a valid sitemap

If your website lacks a valid sitemap, use the Search The Web feature, which relies on Bing search to extract relevant information from the web. This will perform a web search each time a user queries information from the relevant KB.

For manual, specific crawling tasks, you can integrate additional solutions or manually validate crawled content.

## Use the Autonomous Node

For KBs built with Tables, we recommend using the Autonomous Node. It's pre-configured to search and return relevant answers from a KB source.

<Note>
  Note

  There are specific configurations in order to ensure the Autonomous Node behaves as expected.

  [Learn more here.](/docs/studio/concepts/nodes/autonomous-node)
</Note>

## Other knowledge ingestion methods

In addition to manually uploading files, Botpress provides automated methods for ingesting data into the KB.

### Direct API Calls (Files API)

You can integrate Botpress with your existing systems and applications to insert documents or other data directly into the KB.

#### Example

Your CRM system sends updated product info to Botpress KB automatically when a new product is added.

### Fixed Scheduler (cron job)

Set up a cron job that periodically calls your APIs to fetch data, which can then be synced to a KB or table in Botpress using an Execute Code Card.

#### Example

A nightly task pulls inventory data from your ERP system, updating a table in the KB with new product details.

### Webhook (Trigger)

External systems (such as Jira, Zendesk, or other third-party apps) can push data directly to Botpress through webhooks. In Botpress, this data can be processed and synced to a KB or table via an Execute Code Card.

#### Example

When a new support ticket is created in Zendesk, a webhook sends relevant details to Botpress to keep the bot updated with the latest customer issues.

Adding extra preprocessing steps in the Execute Code Card can ensure the incoming data is well-prepared for the KB.


# Autonomous Node
Source: https://botpress.com/docs/studio/concepts/nodes/autonomous-node



The Autonomous Node **uses AI to make decisions**—like what your bot should say or what tools it should use.

Unlike a [standard Node](/docs/studio/concepts/nodes/introduction#standard-node), which executes its [Cards](/docs/studio/concepts/cards) one by one, the Autonomous Node uses a Large Language Model (LLM) to decide when to execute tools. It can understand the conversation's context, write responses to users, and leverage the tools you give it.

<Frame>
  <img alt="alt" />

  <img alt="alt" />
</Frame>

You can use the Autonomous Node to build an independent AI agent that:

* Aligns with your brand
* Learns your users' needs
* Doesn't need human intervention to take actions

***

## Add an Autonomous Node

By default, every bot has an Autonomous Node installed in its main [Workflow](/docs/studio/concepts/workflows). If you need to create a new Autonomous Node:

1. Right-click anywhere in a Workflow.
2. Select **Autonomous Node**.

***

## Configuration

<Tip>
  If your main Workflow contains an Autonomous Node, you can quickly update its configuration from the Studio's [Home](/docs/studio/concepts/home) page.
</Tip>

Select your Autonomous Node to open its configuration menu. Here's a breakdown of the configuration options:

* **Instructions**: This field is your Autonomous Node's main prompt. Provide clear guidelines in this section—the more specific you are, the better the agent’s decision-making.

  For a detailed guide to prompting, check out the [Prompting tips](#prompting-tips) section.

* **Variables**: This section lets you [give your Autonomous Node access to variables](#give-access-to-variables).

* **Tools**: This section lets you [add tools](#add-tools) that the Autonomous Node can use.

* **Search Knowledge**: This section lets you specify which Knowledge Bases your Autonomous Node can refer to.

* **Workflows**: This section lets you provide additional [Workflows](/docs/studio/concepts/workflows) to the Autonomous Node, which it can execute during a conversation.

* **Exit Conditions**: This section lets you define the conditions under which your Autonomous Node should [exit its loop](#advanced-settings).

### Add tools

You can add tools to your Autonomous Node to expand its capabilities. The LLM powering the Autonomous Node will decide when to use these tools based on your instructions (and the conversation's context).

You can refer to tools using natural language in your instructions—however, your bot may generate better responses if you [refer to them using code](#refer-to-tools-directly).

### Give access to variables

By default, Autonomous Nodes can't read or update [variables](/docs/studio/concepts/variables/overview). If you need to give an Autonomous Node access to a variable:

1. Select the Autonomous Node to open its configuration menu.
2. Under **Variables**, select **+ Add variable(s)**.
3. Select any variable to let the Autonomous Node read it.
4. If you also want to give the Autonomous Node write access to the variable, check **Allow write access**.

<Tip>
  If you don't see the option to **+ Add variable(s)**, make sure you've [created at least one variable](/docs/studio/concepts/variables/overview#create-a-variable).
</Tip>

### Make your Autonomous Node non-conversational

By default, your Autonomous Node responds to every user message in a loop until one of its [exit conditions](#configuration) are met. If you'd rather your Autonomous Node just execute logic without responding to user messages, you can disable **Advanced Settings > Loops until exit condition**.

When this setting is disabled, your Autonomous Node:

1. Processes the user's message
2. Performs some action (if necessary), like executing a tool
3. Transitions to the next Node in the Workflow without responding to the user.

This is useful if you want AI to handle logic behind the scenes, but still hard-code the bot's response.

### Override default models

By default, all Autonomous Nodes use the LLMs set in your [Bot Settings](/docs/studio/concepts/bot-settings#default-llms). However, you can override these models for individual Autonomous Nodes if needed:

1. Select the Autonomous Node to open its configuration menu.
2. Open **<Icon icon="chevron-right" />Advanced settings**.
3. Enable either:
   * **Override default model**: Overrides the default LLM used for generating responses
   * **Override default RAG model**: Overrides the default LLM used for Retrieval-Augmented Generation (RAG) tasks, like answering questions based on [Knowledge Base](/docs/studio/concepts/knowledge-base/introduction) content

### Enable Vision Agent

You can enable the [Vision Agent](/docs/studio/concepts/agents/vision-agent) if you want your Autonomous Node to extract text content from incoming images. Toggle **Advanced Settings > Vision Agent > Extract from Incoming Images** to enable or disable this option.

***

## Prompting tips

Here are some tips and guidelines to help you write better prompts for the Autonomous Node.

<Tip>
  You can also check out the following resources for more general information about successful LLM prompting:

  * [Best practices for prompt engineering with the OpenAI API](https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api)
  * [Building Systems with the ChatGPT API](https://www.deeplearning.ai/short-courses/building-systems-with-chatgpt/)
  * [ChatGPT Prompt Engineering for Developers](https://www.deeplearning.ai/short-courses/chatgpt-prompt-engineering-for-developers/)
</Tip>

### Use Markdown

To create a structured prompt, we recommend using [Markdown syntax](https://www.markdownguide.org/basic-syntax/) like headers, bullet points, and bold text. This helps the Autonomous Node recognize the hierarchy of your instructions.

<Accordion title="Example">
  ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  ## Identity
  You are the Customer Support AI Agent for [COMPANY NAME]. Your role is to interact with customers, address their inquiries, and provide assistance with common support topics.

  ## Scope
  - Focus on customer inquiries about orders, billing, account issues, and general support.
  - **Don't handle advanced technical support or sensitive financial issues**.
  - Redirect or escalate issues outside your expertise to a human agent.

  ## Response Style
  - Maintain a friendly, clear, and professional tone.
  - Keep responses brief and to the point.
  - **Never use unexplained jargon or acronyms.**
  - **Always confirm and echo user inputs before proceeding.**
  ```
</Accordion>

### Be specific

Instead of vague commands, use specific language that guides the agent clearly. The more specific you are, the better chance you have of your Autonomous Node behaving as expected.

<Warning>
  #### Don't over-prompt!

  If your prompt is long and detailed but the Autonomous Node isn't behaving how you'd expect, **try trimming the prompt down**. An overly convoluted (or contradictory) prompt can confuse the LLM and lead to poor performance or hallucinations.
</Warning>

### Guide the conversation

Provide clear instructions on how the conversation should flow. This could include:

* Greeting instructions
* Conditions for [transitioning to sub-Workflows](/docs/studio/concepts/workflows#transition-to-a-workflow)
* Closing instructions

<Accordion title="Example">
  ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  ## Instructions
  - **Greeting**: Start every conversation with a friendly welcome.
    _Example_: "Hi, welcome to [COMPANY NAME] Support! How can I help you today?"

  - **Escalation**: When a customer query becomes too complex or sensitive, transition to the "Human agent" sub-Workflow and notify the customer that you'll escalate the conversation to a human agent.
    _Example_: "I’m having trouble resolving this. Let me get a human agent to assist you further."

  - **Closing**: End interactions by confirming that the customer's issue has been addressed.
    _Example_: "Is there anything else I can help you with today?"
  ```
</Accordion>

### Refer to tools directly

Your bot uses various code-based tools to perform actions. Although you can write your instructions in natural language, your bot may generate better responses if you refer to these tools directly.

You can view a full list of tools your bot currently has access to in the [Inspect window](#inspect-window).

<Tabs>
  <Tab title="Default tools">
    Here's a list of built-in tools that every bot can use by default:

    * `global.think`: Allows the Node to process a response or pause briefly.
    * `global.search`: Queries an internal knowledge base for relevant information.
    * `clock.setReminder`: Sets a reminder for future tasks or responses.
    * `global.Message`: Sends a text message to the user as a response.

    <Accordion title="Example: Search the web">
      This prompt tells the Autonomous Node to search the web when it can't find an answer in the internal Knowledge Base:

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      If you can't answer the user's question with `global.search`, use `browser.webSearch`.
      ```
    </Accordion>

    <Accordion title="Example: Keep knowledge and web search on-topic">
      This prompt narrows when each search tool runs so the Node doesn't pull unrelated content:

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      **Tool boundaries**
      - Use `global.search` only for questions about [your scoped topic—for example course content or order support]. Do **not** use it for general pricing, marketing, or unrelated small talk unless the user explicitly needs a documented policy from the knowledge base.
      - Use `browser.webSearch` only when `global.search` does not contain a sufficient answer **and** the question still falls within that same scope. Do not use web search for out-of-scope requests—politely decline instead.
      ```
    </Accordion>

    <Accordion title="Example: Video link with a timestamp">
      When the base URL lives in a [Workflow variable](/docs/studio/concepts/variables/scopes/workflow), this prompt tells the Autonomous Node how to add a start time (replace the variable name with one you have given the Node access to):

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      **Video links**
      If the user wants a link to the lesson video, the base URL is in `workflow.contentLinks`. To jump to a specific second, append a `t` query in seconds (e.g. 15 seconds → add `?t=15` or `&t=15` depending on whether the URL already has query parameters).
      ```
    </Accordion>
  </Tab>

  <Tab title="Transition tools">
    Here are the tools your bot uses to make transitions:

    * `global.<workflowName>`: [Transitions to a sub-Workflow](/docs/studio/concepts/workflows#transition-to-a-workflow).
    * `workflow.transition`: Transitions to a Node that's connected to the Autonomous Node.

    <Accordion title="Example: Checkout Workflow">
      This prompt tells the Autonomous Node to transition to a custom sub-Workflow (`global.checkout`) when the user wants to checkout with their current cart:

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      When the user wants to checkout with their current cart, use `global.checkout`.
      ```
    </Accordion>

    <Accordion title="Example: Transition and set a variable">
      This pattern is for leaving the Autonomous Node for a structured sub-Workflow after saving a value from the conversation. The Autonomous Node needs [read and write access](#give-access-to-variables) to the variable you mention:

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      When the user asks for deeper details about an email they mentioned, use `workflow.transition` to move to the **Enrich contact** Node. Before transitioning, set `workflow.requestedEmail` to that email address.
      ```

      Replace the Node name, variable name, and trigger phrase with whatever matches your bot.
    </Accordion>

    <Accordion title="Example: Menu choice, then transition">
      This prompt combines `global.Message` with `workflow.transition` when the user picks a numeric option. Connect each target with a **Transition** card on the canvas first so `workflow.transition` is valid:

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      If the user sends **1**, thank them briefly with `global.Message`, then use `workflow.transition` to go to the **Self-serve** node. If they send **2**, use `workflow.transition` to go to the **Guided setup** node.
      ```
    </Accordion>
  </Tab>

  <Tab title="Integration tools">
    You can also directly refer refer to any tools from external integrations.

    <Accordion title="Example: HITL integration">
      This prompt tells the Autonomous Node to start a [Human-in-the-loop (HITL)](/docs/integrations/integration-guides/hitl/introduction) session when the user indicates they'd like to speak to a live agent:

      ```markdown Instructions wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      When the user indicates they'd like to speak to a live agent, use `hitl.startHitl`.
      ```
    </Accordion>
  </Tab>
</Tabs>

***

## Example instructions

Here's an example of complete instructions for an Autonomous Node:

```markdown Instructions expandable wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## Identity
You are the Customer Support AI Agent for [COMPANY NAME]. Your role is to interact with customers, address their inquiries, and provide assistance with common support topics.

## Scope
- Focus on customer inquiries about orders, billing, account issues, and general support.
- Don't handle advanced technical support or sensitive financial issues.
- Redirect or escalate issues outside your expertise to a human agent.

## Responsibility
- Initiate interactions with a friendly greeting.
- Guide the conversation based on customer needs.
- Provide accurate and concise information.
- Escalate to a human agent when customer inquiries exceed your capabilities.

## Response Style
- Maintain a friendly, clear, and professional tone.
- Keep responses brief and to the point.
- Use buttons for quick replies and easy navigation whenever possible.

## Ability
- Delegate specialized tasks to AI-Associates or escalate to a human when needed.

## Guardrails
- **Privacy**: Respect customer privacy; only request personal data if absolutely necessary.
- **Accuracy**: Provide verified and factual responses coming from Knowledge Base or official sources. Avoid speculation.

## Instructions
- **Greeting**: Start every conversation with a friendly welcome.
  _Example_: "Hi, welcome to [COMPANY NAME] Support! How can I help you today?"

- **Escalation**: When a customer query becomes too complex or sensitive, notify the customer that you'll escalate the conversation to a human agent.
  _Example_: "I’m having trouble resolving this. Let me get a human agent to assist you further."

- **Closing**: End interactions by confirming that the customer's issue has been addressed.
  _Example_: "Is there anything else I can help you with today?"
```

***

## Troubleshooting

This section contains troubleshooting tips to understand how your Autonomous Node is behaving, why it made certain decisions, and how you can course-correct when it's not behaving as expected.

### Check the Inspect window

The **Inspect** window displays information about the Autonomous Node's process, reasoning, and functions. If you notice that the Node isn’t responding correctly or seems to ignore certain instructions, inspecting will reveal whether it has misunderstood the prompt or failed to execute a specific tool.

To access the **Inspect** window:

1. Start a chat with your bot in the Studio's [emulator](/docs/studio/concepts/emulator).
2. Select **Inspect** on any of its responses.

Here's a breakdown of how to use the **Inspect** window:

<AccordionGroup>
  <Accordion title="Tools">
    This section displays all tools available to the Autonomous Node. Each time you add a new Card or make a change to the Node's configuration, the **Tools** list is updated.

    * Ensure that the tools listed match what you expect to be available in the Node's decision-making process.
    * Ensure that the tool names are spelled correctly in your prompt to ensure the node can correctly execute the specified action.
  </Accordion>

  <Accordion title="Iterations">
    The Autonomous Node typically tries to execute all instructions within one or two iterations. The number of iterations depends on the complexity of the prompt and how the Node analyzes it.

    For more complex tasks, the Node might take multiple iterations to gather data, make decisions, or fetch external information.

    By reviewing the Iterations tab, you can understand:

    * How many iterations were required for the Node to reach its final decision
    * What caused the Node to take multiple steps (e.g., fetching additional data from tools like `global.search` or `browser.webSearch`)
    * Why a particular outcome was achieved
  </Accordion>
</AccordionGroup>

### Choose the right model

Lower-performance LLMs may struggle with the complexity of operations typically executed by the Autonomous Node. For this reason, we recommend using a high-performing model to power Autonomous Nodes, roughly equivalent to a model like OpenAI's GPT-4.1.

A smaller LLM might result in parts of the prompt being truncated, specifically the definition wrapper that Botpress adds to ensure the LLM understands how the tools function, or what parameters are required.

### Check your LLMz version

Always make sure you are using the latest stable version of LLMz. This is the autonomous engine that directs the Autonomous Node to work. It also contains bug fixes, making the prompts more agnostic to variance between LLMs.

You can check/change your LLMz version in your [Bot Settings](/docs/studio/concepts/bot-settings#llmz-version).


# Nodes
Source: https://botpress.com/docs/studio/concepts/nodes/introduction



Nodes are the **primary units of conversational logic** in your bot.

Think of a Node as a single step in a conversation. It executes a sequence of actions—like sending a message, capturing information from a user, or performing a task—then transitions to the next Node.

<Frame>
  <img alt="Nodes" />

  <img alt="Nodes" />
</Frame>

***

## Overview

An individual Node's behaviour depends on what [Cards](/docs/studio/concepts/cards/introduction) it contains. You can add any combination of Cards to a Node to achieve your desired behaviour.

A Node [transitions to the next Node](#transition-between-Nodes) when either:

* It finishes executing all its Cards
* One of its Cards manually transitions to a new Node. You can set up manual transitions based on [user choice](/docs/studio/concepts/cards/capture-information), [true/false conditions](/docs/studio/concepts/cards/flow-logic), and more.

<Note>
  Some Nodes have specific properties that make them behave differently—check out [Types of Node](#types-of-node) for
  more details.
</Note>

<Tip>
  A group of Nodes is called a [Workflow](/docs/studio/concepts/workflows). You can use Workflows to organize your bot's
  behaviour.
</Tip>

***

## Usage

### Add a Node

To add a new Node:

1. Right-click anywhere in a Workflow.
2. Select a [type of Node](#types-of-node) from the popup menu.

### Transition between Nodes

To create a transition between two Nodes:

1. Select and hold the right edge of the Node you want to transition *from*.
2. Drag outwards, then release on the left edge of the Node you want to transition *to*. This will create a transition between the two Nodes:

<Frame>
  <img alt="Transition" />

  <img alt="Transition" />
</Frame>

### Move a Node

To move a Node around your Workflow, just drag and drop it wherever you like.

### Rename a Node

To rename a Node, just select its title and type in a new name.

### Test a Node

You can test a specific Node in the Studio's [Emulator](/docs/studio/concepts/emulator). Just select any Node, then press the <Icon icon="play" /> Play button to start a conversation with your bot from that Node.

### Copy/Delete a Node

Right-click any Node to copy or delete it.

***

## Types of Node

Nodes behave differently and have different available Cards based on their type. Here's a breakdown of each type of Node:

### Standard Node

Standard Nodes execute each of their Cards one-by-one, then transition to the next Node. They're the most basic type of Node, and are useful when you need full control over your bot's behaviour.

### Autonomous Node

The Autonomous Node uses AI to make decisions—like what your bot should say or what tools it should use.

Unlike a standard Node, which executes its Cards one by one, the Autonomous Node uses a Large Language Model (LLM) to decide when to execute its Cards. It can understand the conversation’s context, write responses to users, and leverage the tools you give it.

<Tip>For more information, check out the [Autonomous Node guide](/docs/studio/concepts/nodes/autonomous-node).</Tip>

### Start Node

The Start Node is the entrance point to every conversation with your bot. It's only available in the [Main Workflow](/docs/studio/concepts/workflows#main), can't be modified/deleted, and can't use Cards.

You can select the Start Node to configure:

* Which [Knowledge Base](/docs/studio/concepts/knowledge-base/introduction) your bot has access to
* Whether your bot has access to the [Vision Agent](/docs/studio/concepts/agents/vision-agent)

### Entry Node

The Entry Node is the start of every Workflow in your bot (except for the [Main Workflow](/docs/studio/concepts/workflows#main)). It executes whenever you [transition to a new Workflow](/docs/studio/concepts/workflows#transition-to-a-workflow) and can't be deleted.

The only Cards you can add to an Entry Node are:

* [Expression/Intent](/docs/studio/concepts/cards/flow-logic) Cards
* [Log](/docs/studio/concepts/cards/utilities#log) Cards

<Tip>
  You can toggle variables within an Entry Node—check out the guide to [passing variables between
  Workflows](/docs/studio/concepts/variables/pass-between-workflows) for more information.
</Tip>

### Exit Node

The Exit Node is the end of every custom Workflow in your bot ([built-in Workflows](/docs/studio/concepts/workflows#built-in-workflows) end with an [End Node](/docs/studio/concepts/nodes/introduction#end-node) instead). It defines the exit point for the Workflow—each custom Workflow must contain at least one Exit Node.

Exit Nodes can't use Cards.

<Tip>
  You can configure the Exit Node to pass a variable back to its parent Workflow—check out the guide to [passing
  variables between Workflows](/docs/studio/concepts/variables/pass-between-workflows) for more information.
</Tip>

### End Node

The End Node is the end point of every conversation with your bot. It has no configuration options and can't use Cards.

Only End Nodes can explicitly end a conversation, which:

* Clears the conversation session
* Erases all variables and user data
* Resets the bot to its initial state.

Each [built-in Workflow](/docs/studio/concepts/workflows#built-in-workflows) must contain at least one End node. You can also add End Nodes to custom Workflows.

### Triggers

Triggers are a special kind of Node that only execute when a certain event occurs. They're different from regular Nodes in a few ways:

* You can’t transition from a regular Node to a Trigger. Any Triggers in your Workflow will only execute when the event they listen for occurs.
* Unlike other Nodes, you can’t add or remove Cards from a Trigger. Each Trigger is built around a single Card that determines when it executes.

<Tip>For more information, check out the [Triggers guide](/docs/studio/concepts/triggers).</Tip>

### Exception handlers

Exception handlers are Nodes that execute whenever your bot encounters an error. They're optional, have no configuration options, and can't contain any Cards.

By default, your bot uses the built-in [Error Workflow](/docs/studio/concepts/workflows#error) to handle errors, regardless of which Workflow the error occurred in—exception handlers let you handle errors differently for specific Workflows.

You can only add exceptional handlers to the [Main Workflow](/docs/studio/concepts/workflows#main) or to custom Workflows. Each Workflow can contain one exception handler.

### Comments

You can leave comments, images or videos in your Workflow. They have no effect on your bot's behaviour—you can use them to annotate your Workflows and make them easier to understand for any collaborators.


# Schemas
Source: https://botpress.com/docs/studio/concepts/schemas

Blueprint that defines the structure, format, and validation rules for data.

A schema is a blueprint that defines the structure, required fields, data types, and validation rules for a piece of data. In Botpress, schemas are primarily used to ensure that data passed between various components—such as actions, modules, or API requests—meets the expected format and constraints.

Schemas are useful for:

* **Data Validation**: Preventing errors by ensuring that data adheres to the expected format.
* **Consistency**: Enforcing a consistent structure for data across different components.
* **Error Reduction**: Reducing the likelihood of runtime errors caused by unexpected or malformed data.

- **Ease of Maintenance**: Making it easier to understand and manage data flow within your Botpress application.

## Creating and Using Schemas

### JSON Schema Basics

Botpress uses JSON Schema, a standard for describing the structure and validation constraints of JSON documents.

A JSON Schema can define:

* **Types**: The type of data (e.g., string, number, object, array).
* **Required Fields**: Fields that must be present in the data.
* **Enum Values**: Specific allowed values for a field.
* **Nested Structures**: Complex data structures with multiple levels.

### Creating a schema

You can create a new schema by navigating to the Schema menu in the left-hand menu. You can also create a new schema when adding a new variable through the Variables menu.

### Using schemas

You can use schemas instead of selecting a variable type like String or Number. This means that the variable will contain the information in the structure you've defined in your schema.

For example, you might use a variable to contain information about your end user. This variable can use a schema to contain information like email, age, name, and home address, all contained in a single variable and structured by your schema.

## Testing Schemas

Here's a simple demo schema you can create to familiarize yourself with them.

1. Create a schema for a user object with the following properties:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
zui.object({
  name: zui.string(),
  age: zui.number(),
  email: zui.string().email(),
  address: zui.object({
    street: zui.string(),
    city: zui.string(),
    zip: zui.string().length(5)
  })
})
```

2. Create a Variable of the user schema type and name it `UserInformation`.
3. \[optionally] you can use these variables as inputs for Workflows, allowing the user to fill in the schema as though it were a form.

### Usage in AI Task

* Task Instructions:

```
Fetch name, age, email and address from the provided input
```

* AI Task Input:

```
Rohan Kokkula, 26, at rohan@email.com, received a mysterious parcel at his doorstep:
42 Emerald Lane, Mystic Falls, 560078.
Inside, a map beckoned him to a hidden world beneath Mumbai's bustling streets,
where history and magic intertwined.
```

* Store result in variables: Select the Variable we created above.

<br />

## Conditionally Show Inputs - Input trees

We'll show you how to use discriminated unions in Zod to conditionally include fields in an object schema. We'll go through two examples:

1. Changing the type of a variable based on user input.
2. Conditionally showing an extra setting when an "Advanced Setting" toggle is activated.

<img />

<br />

<img />

#### Example 1: Changing the Type of a Variable

In this example, we'll create a schema that allows a variable (`value`) to be either a string or a number, depending on the user's choice.

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
z.object({
  inputData: z.discriminatedUnion('inputType', [
    z.object({
      inputType: z.literal('Text'),
      // When inputType is 'Text', value is a string
      value: z.string().title('Text Value').placeholder('Enter text')
    }),
    z.object({
      inputType: z.literal('Number'),
      // When inputType is 'Number', value is a number
      value: z.number().title('Numeric Value').placeholder('Enter a number')
    })
  ])
});
```

##### How It Works

* **`inputType`**: Acts as the discriminator that determines the type of the `value` field.
* **Discriminated Union**:
  * If `inputType` is `"Text"`, the schema expects `value` to be a string.
  * If `inputType` is `"Number"`, the schema expects `value` to be a number.

This approach is useful when you want to change the type of a variable based on a user's selection.

#### Example 2: Conditionally Showing Extra Settings

This example demonstrates how to include an extra field when an "Advanced Setting" toggle is turned on.

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
z.object({
  // ... your other inputs

  // Using discriminated union to handle the advanced setting toggle with Yes/No options
  settings: z.discriminatedUnion('advancedSetting', [
    z.object({
      advancedSetting: z.literal('No').describe('Advanced setting is disabled'),
      // No extra settings when advancedSetting is "No"
    }),
    z.object({
      advancedSetting: z.literal('Yes').describe('Advanced setting is enabled'),
      // Extra setting when advancedSetting is "Yes"
      extraSetting: z.string()
        .title('Extra Setting')
        .placeholder('Enter extra setting')
        .describe('Additional setting enabled when the advanced setting is turned on')
    })
  ])
});
```

##### How It Works

* **`advancedSetting`**: Acts as the discriminator that determines whether to include the `extraSetting` field.
* **Discriminated Union**:
  * If `advancedSetting` is `"No"`, the schema doesn't include `extraSetting`.
  * If `advancedSetting` is `"Yes"`, the schema requires `extraSetting` to be provided.

This pattern is useful when you want to include additional settings only when an "Advanced Setting" option is enabled.

#### Trying it out

Trying it out is very easy!

1. Open Botpress Studio
2. Create and save the schema with `discriminatedUnion` fields
3. Create a variable in a Workflow other than main, set its type to the schema's saved name.
4. Click on the input node for the Workflow, then toggle the variable as an input.
5. Go to another Workflow and add a card that points to the one with the schema input.
6. You'll now be able to able to see your input tree in all it's glory!

#### Summary

* **Discriminated Unions** in Zod allow you to conditionally change the shape of an object.
* They're useful for:
  1. Changing the type of a variable based on user input.
  2. Conditionally including fields based on a toggle or option.

By using discriminated unions, you can build dynamic and flexible schemas that adapt based on user selections, making your form validation and UI more intuitive and responsive.


# Tables
Source: https://botpress.com/docs/studio/concepts/tables



Tables are an essential feature in the explorer, functioning as a local database within your bot's environment. They provide structured storage for various types of data that can be accessed and manipulated as required within your Workflows.

They're particularly useful for storing information that needs to be persisted across multiple sessions, such as user profiles, transaction histories, and other types of data that need to be retrieved and updated over time.

<Note>
  Note

  You can create up to **10 tables** with **20 columns** and **10,000 rows** in the **Free Plan**. [Get in touch](https://botpress.com/contact-us) if you want to increase the limits. However, the 20 columns per table is a hard limit that can't be increased.
</Note>

<Warning>
  Table row capacity filling up quicker than you expected? Check your table's **row factor**.

  <div>
    <Accordion title="What are row factors?">
      Every table has a row factor that determines the storage limit for each of its rows. When you create a new table, the default row factor is 1—this allows you store up to 4KB of data per row.

      If you need to store more than 4KB of data in each row, you can create a table with a higher row factor. However, increasing the table's row factor makes each row count more towards your table's row limit.

      **Example**: If you create a table with a row factor of 3, each row will have a storage limit of 12KB (because 4KB x 3 =  12KB). This will make each row will count as three rows towards your table's row limit.

      You can check any table's row factor in the bottom-right corner of that table.
    </Accordion>
  </div>
</Warning>

## Creating a Table

To add a new table, go to the explorer menu and select `Add Table`. You can then give your table a name and add fields to it. Each field has a name and a type. The type determines the kind of data that can be stored in the field. For example, a field with the type `String` can store any text value, while a field with the type `Number` can only store numeric values.

### Making Fields Searchable

You can make a field searchable by checking the `Searchable` checkbox. This will allow you to search for records based on the values in the field. For example, if you have a field called `Name` and you make it searchable, you can search for records based on the name of the person. This is available for fields of type `String`, `Object`, `Array` and [custom schemas](/docs/studio/concepts/schema).

## Types of Fields (Columns)

There are several types of fields you can add to a table. Each field type has a specific purpose and can only store certain types of data. These are the field types you can choose from: `String`, `Number`, `Boolean`, `Date`, `Object`, `Array` and [custom schemas](/docs/studio/concepts/schema).

<Warning>
  Warning

  The number of columns has a hard limit of **20 columns** per table.
</Warning>

## Filtering Records

Table filters are a powerful feature that allows you to refine and display only the records that meet certain criteria. Filters can be based on specific conditions, such as date ranges, text matches, and numerical comparisons.

### Logical Operators

* **AND**: Use the AND operator when you want all conditions to be true for a record to be displayed. For example, filtering by `createdAt` AND `status` will only show records that match both conditions.

* **OR**: Use the OR operator to display records that match any one of multiple conditions. For example, filtering by `createdAt` OR `updatedAt` will show records that match either one of the conditions.

### Types of Rules

Rules define the individual conditions applied to each column of data.

* `is equal to`: Shows records where the field is equal to the specified value.
* `is not equal to`: Shows records where the field isn't equal to the specified value.
* `less than`: Shows records where the field is less than the specified value.
* `less than or equal to`: Shows records where the field is less than or equal to the specified value.
* `greater than`: Shows records where the field is greater than the specified value.
* `greater than or equal to`: Shows records where the field is greater than or equal to the specified value.
* `in`: Shows records where the field matches any of the specified values.
* `not in`: Shows records where the field doesn't match any of the specified values.
* `is null`: Shows records where the field is empty.
* `is not null`: Shows records where the field isn't empty.

### Rule Groups

* **Group**: A group is a collection of rules combined by a logical operator (AND/OR). You can nest groups to create complex filters.

### Creating a Filter

1. Click on the `Filter` button to expand the filter menu.
2. Select a logical operator (AND/OR) from the dropdown.
3. Choose a field to filter by (e.g., `createdAt`).
4. Select a rule (e.g., `is equal to`).
5. Enter the required value or select from a calendar if it's a date field.
6. To add another rule within the same logical condition, click the `+ Rule` button.
7. To create a nested group of conditions, click the `+ Group` button.
8. Apply the filter by clicking the `Apply filter` button.

### Manually Editing Filters

Click on **Edit Manually** to view and edit the filter in JSON format. You can then copy this JSON filter and use it in your table operations via code.

## Operations on Tables - via the Interface

### Add records to a table

Once you've created a table, you can add records to it. To do this, click on the table in the explorer menu. You'll then see a list of all the records in the table. Click on the `Add Record` button to add a new record. You can then enter the values for each field in the record.

### Update records in a table

Double click on a table cell or press click it and press `Enter` to see an input that allows you to change the cell value. Once you are done, press `Enter` again or click away to save the new value.

### Delete records from a table

`Right Click` on the Record and select `Delete Record` to delete a record from a table.

## Operations on Tables - via Cards

Check out the [Table Cards documentation](/docs/studio/concepts/cards/execute-code#table-cards) to learn more about operations with cards.

## Operations on Tables - via Botpress Client

You can also interact with tables using the Botpress Client. Here are some of the functions you can use to interact with tables:

### List tables

To list all the tables in the bot, use the `listTables` function. This function will return an array of all the tables in the bot.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
try {
  const tables = await client.listTables({})
  console.log('Tables:', tables)
} catch (err) {
  console.error('Error fetching tables', err)
}
```

### Create Table Rows

Execute the following query to create one or multiple rows. The response will include the inserted rows, along with any encountered errors or warnings during the operation (e.g., unrecognized fields)

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows, errors, warnings } = await client.createTableRows({
  table: 'Data1Table',
  rows: [
    {
      name: 'test',
    },
  ],
})
```

### Find & Filter Table Rows

To find and filter rows in a table, use the `findTableRows` function. You can specify the limit (number of records to return) and the offset (number of rows to start from).

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows, limit, offset, count } = await client.findTableRows({
  table: 'Data1Table',
  limit: 50,
  offset: 0,
  filter: {},
  orderBy: 'row_id',
  orderDirection: 'asc',
})
```

Utilize filters to conduct more refined queries for specific rows, employing a MongoDB-like syntax. The query builder aids in understanding available operations and constructing the filter.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows, limit, offset, count } = await client.findTableRows({
  table: 'Data1Table',
  filter: {
    // Retrieve rows where date is greater than a specific date
    updatedAt: { gte: '2024-01-01' },
    // Or more complex conditions, such as name starting with 'a' or 'b', or 'isActive' being true
    $or: [{ name: { $regex: '^a' } }, { name: { $regex: '^b' } }, { isActive: true }],
  },
})
```

The "search" property allows for a partial text search across the table. The query returns multiple results, each accompanied by a similarity score to indicate relevance.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows, limit, offset, count } = await client.findTableRows({
  table: 'Data1Table',
  search: 'John Doe',
})
```

### Projection & Aggregation

Employ the group property for projections and aggregations. The following example demonstrates returning a single row with requested data.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await client.findTableRows({
  table: 'Data1Table',
  group: {
    id: 'count',
    name: ['unique', 'count'], // will return a list of unique values & the total count
    updatedAt: ['min', 'max'], // Retrieves the earliest and latest date
  },
})

// Output variables are named after the field, suffixed with the operation
const oldestChange = rows[0].updatedAtMin
const mostRecentChange = rows[0].updatedAtMax
const count = rows[0]['nameCount']
const uniqueValues = rows[0]['nameUnique']
```

<table>
  <thead>
    <tr>
      <th>
        Column
      </th>

      <th>
        Type
      </th>

      <th>
        Key
      </th>

      <th>
        Count
      </th>

      <th>
        Sum
      </th>

      <th>
        Avg
      </th>

      <th>
        Max
      </th>

      <th>
        Min
      </th>

      <th>
        Unique
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        id
      </td>

      <td>
        number
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>
    </tr>

    <tr>
      <td>
        createdAt
      </td>

      <td>
        date
      </td>

      <td>
        ✔️
      </td>

      <td />

      <td />

      <td />

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>
    </tr>

    <tr>
      <td>
        updatedAt
      </td>

      <td>
        date
      </td>

      <td>
        ✔️
      </td>

      <td />

      <td />

      <td />

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>
    </tr>

    <tr>
      <td>
        name
      </td>

      <td>
        string
      </td>

      <td>
        ✔️
      </td>

      <td />

      <td />

      <td />

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>

      <td>
        ✔️
      </td>
    </tr>
  </tbody>
</table>

**Key**: Projections are grouped by keys (ex: date)\
**Count**: Returns the total number of non-null values\
**sum**: Returns the sum of all values\
**Avg**: Returns the average of all values\
**Max**: Returns the maximum value\
**Min**: Returns the minimum value\
**Unique**: Returns a list of unique values

Providing one or multiple keys yields more specific results.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows } = await client.findTableRows({
  table: 'Data1Table',
  group: {
    someField: 'key', // Either provide a single operation
    someNumber: ['avg', 'sum'], // Or multiple operations
  },
})

// Returns multiple rows for each unique combination of keys
const result = rows.map((row) => {
  const { someFieldKey, someNumberAvg, someNumberSum } = row
})
```

### Update Table Rows

This operation updates rows based solely on their numeric IDs.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows, errors, warnings } = await client.updateTableRows({
  table: 'Data1Table',
  rows: [
    {
      id: 1,
      name: 'test',
    },
  ],
})
```

### Delete Table Rows

Rows can be deleted from a table in three distinct manners, each mutually exclusive.

By specifying row IDs\
By applying a filter\
By removing all rows

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { deletedRows } = await client.deleteTableRows({
  table: 'Data1Table',
  // Specify a list of IDs
  ids: [1, 2, 3],
  // Or use a filter (caution: all rows matching the filter will be deleted. It's advisable to first test with the findTableRows query)
  filter: { name: 'John Doe' },
  // Deletes every row within this table, irreversible action
  deleteAllRows: true,
})
```

### Upsert Table Rows

The upsert operation is a combination of insert or update, allowing you to insert new rows or update existing ones. The operation is based on the row's `keyColumn`.

`keyColumn`: The column used to identify the row. This column must be unique. Failure occurs if more than one row is found for the same key.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { rows, inserted, updated, errors, warnings } = await client.upsertTableRows({
  table: 'Data1Table',
  keyColumn: 'email',
  rows: [
    {
      email: 'hello@world.com', // will update this row, or create a new one if not found
      name: 'test',
    },
  ],
})
```

### Create Table

To create a table, simply provide a name and a schema. The naming convention follows the same rules as those applied within the studio. Initially, the schema can be empty and populated or modified later. The schema accepts either an example object, from which it will infer the structure, or a directly provided JSON schema.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table } = await client.createTable({
  name: 'Data1Table',
  schema: {
    name: 'test',
  },
})
```

Example using a JSON schema. A field marked as 'searchable' will be indexed, enhancing its availability for search queries. Note, 'index' is a system-managed, read-only attribute.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table } = await client.createTable({
  name: 'Data1Table',
  schema: {
    type: 'object',
    'x-zui': {},
    properties: {
      name: {
        type: 'string',
        'x-zui': {
          index: 0,
          searchable: true,
        },
        nullable: true,
      },
    },
    additionalProperties: true,
  },
})
```

### Update Table

You can update a table's name, schema, or both. Providing only one of these attributes is also permissible. Should you alter the type of an existing column, be advised that all its entries will default to NULL.

#### Adding a new field

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table } = await client.updateTable({
  table: 'Data1Table',
  schema: {
    myNewField: 'abc', // Direct value assignment
    // Or specify with a JSON schema
    myNewField: { type: 'string' },
  },
})
```

#### Removing an existing field:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table } = await client.updateTable({
  table: 'Data1Table',
  schema: {
    myOldField: null, // Field removal
  },
})
```

#### Renaming the table

A table name must end with "Table".

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await client.updateTable({ table: 'Data1Table', name: 'myNewTable' })
```

#### Rename Table Column

To rename a table column, specify both the current and new names. The column's data type and attributes will remain unchanged.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table } = await client.renameTableColumn({
  table: 'Data1Table',
  name: 'My Old Column Name',
  newName: 'New Column Name',
})
```

### Get Table

To retrieve a table's schema, use the `getTable` function. This will return the table definition, along with the total number of rows, number of stale rows and number of indexing rows.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table, indexing, rows, stale } = await client.getTable({ table: 'Data1Table' })
```

### Delete Table

To delete a table, use the `deleteTable` function. This will permanently remove the table and all its records.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { table } = await client.deleteTable({ table: 'Data1Table' })
```

## Operations on Tables - via Code

<img />

### Create record

To create a new record in a table, use the `createRecord` function. You can specify the values for each field in the record. This function can be particularly useful when you need to store new information, such as a new user's details or a newly completed transaction.

<YouTube />

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Create a record in the table
await Data1Table.createRecord({ Age: 25, Name: 'Tom', Occupation: 'Student' })
```

### Create records

To create multiple records in a table, use the `createRecords` function. You can specify the values for each field in the record. Useful for creating multiple records at once.

<YouTube />

```JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Creating two records in the table
await Data1Table.createRecords([
  { Name: 'Tom', Age: 25, Occupation: 'Student', 'Is Friendly': true },
  { Name: 'Didier', Age: 54, Occupation: 'Pilot', 'Is Friendly': true },
])
```

### Delete record

To delete a record in a table, use the `deleteRecord` function. You need to specify the record ID of the record you want to delete.

<YouTube />

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Delete a record in the table at record ID 7
await Data1Table.deleteRecord(7)
```

### Delete records

To delete multiple records in a table, use the `deleteRecords` function. You need to specify the record IDs of the records you want to delete in an array.

<YouTube />

```JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
 // Delete records in the table at record IDs 7, 8, 9
await Data1Table.deleteRecords([7, 8, 9])
```

### Find records

To find records in a table, use the `findRecords` function. You can add filters, just query everything or search using semantic search (like a Google Search!).

#### Basic usage and pagination

To retrieve data from a table in Botpress, you can use the `findRecords` function. This function allows you to specify the limit (number of records to return) and the offset (number of rows to start from).

For instance, if you want the first 10 records, you can set the limit to 10 and the offset to 0. To fetch the next 10 records, you can set the limit to 10 and the offset to 10.

To determine if there are more records available, you can check the length of the array returned. If the length is greater than 0, it indicates the presence of additional records.

Here's an example:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const limit = 10
const startRow = 0

workflow.records = await DataTable1.findRecords({
  limit,
  offset: startRow,
})

// Checking the second page
const secondPage = await Data1Table.findRecords({
  limit,
  filter: AI`everything`,
  offset: startRow + limit,
})

workflow.hasNextPage = secondPage.length > 0 // This flag can be consumed in your bot Workflow to handle pagination
```

You can apply a similar approach to determine if there are previous pages as well.

#### Searching fields with natural language

To perform a traditional search, use the search parameter when calling the DataTable1.findRecords() function in Botpress. Here is an example:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
workflow.records = await DataTable1.findRecords({ search: 'red velvet chairs' })
```

You can pass variables like event.preview to the search parameter to search for user input or any other variable. This allows you to pre-process the user's input before performing the search.

#### Filtering results

You can filter results using filters. Similar to MongoDB, this code provides methods to filter results. The filtering mechanism can be divided into two main categories: Primitive and Logical.

Don't want to deal with code? Skip to the [next section](#using-ai-to-generate-filters) for AI generated filters.

#### **Primitive Filter**

Primitive filters are easy and simple to use, allowing you to match the exact values you are looking for. Here are some of the primitives you can use:

* `$eq`: Matches values that are equal to a specified value.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$eq": "John" } }
  ```

* `$gt`: Matches values that are greater than a specified value.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "age": { "$gt": 20 } }
  ```

* `$gte`: Matches values that are greater than or equal to a specified value.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "age": { "$gte": 20 } }
  ```

* `$lt`: Matches values that are less than a specified value.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "age": { "$lt": 20 } }
  ```

* `$lte`: Matches values that are less than or equal to a specified value.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "age": { "$lte": 20 } }
  ```

* `$ne`: Matches all values that aren't equal to a specified value.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$ne": "John" } }
  ```

* `$in`: Matches any of the values specified in an array.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$in": ["Alice", "Bob", "John"] } }
  ```

* `$nin`: Matches none of the values specified in an array.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$nin": ["Alice", "Bob", "John"] } }
  ```

* `$exists`: Matches documents that have the specified field.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$exists": true } }
  ```

* `$mod`: Performs modulo operation on the value of field and matches documents where field % divisor equals the specified remainder.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "qty": { "$mod": [4, 0] } }
  ```

* `$size`: Matches any document where an array field contains a specified number of elements.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "tags": { "$size": 3 } }
  ```

* `$regex`: Provides regular expression capabilities for pattern matching strings in queries. It uses a placeholder to prevent SQL injections.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$regex": "[a-z]" } }
  ```

* `$options`: Modifies the `$regex` operator to enable options. Currently, there are two options, 'i' for case-insensitive and 'c' for case-sensitive.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "name": { "$regex": "[a-z]", "$options": 'i' } } // case-insensitive

  { "name": { "$regex": "[a-z]", "$options": 'c' } } // case-sensitive
  ```

#### **Logical Filter**

Logical operators allow you to connect more filtering clauses.

* `$and`: Joins query clauses with a logical AND. Returns all documents that match the conditions of both clauses.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "$and": [{ "price": { "$ne": 1.99 } }, { "price": { "$exists": true } }] }
  ```

* `$or`: Joins query clauses with a logical OR. Returns all documents that match the conditions of either clause.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "$or": [{ "price": { "$eq": 1.99 } }, { "price": { "$exists": false } }] }
  ```

* `$not`: Inverts the effect of a query expression and returns documents that don't match the query expression.

  ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  { "$not": { "price": { "$eq": 1.99 } } }
  ```

Please note that these filters and operators can be used together to create complex queries to exactly fit your needs. You can also nest filters like so :

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
   "$and": [
      { "price": { "$lte": 19.99 }},
      { "$or":  [
         {"category": { "$eq": "Shoes" }},
         {"category": { "$eq": "Hats"}}
        ]
      }
   ]
 }
```

If you have a column of type object, you can also use operators on nested paths:

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "customer.name": { "$regex": "[a-z]" },
  "customer.age": { "$gte": 18 }
}
```

#### Using AI to generate filters

Thankfully, Botpress comes with artificial intelligence (AI) capabilities when it comes to filtering records. This means you can provide a human-like query, and the AI will intelligently decipher it and create the right filters for your query.

This can significantly simplify the construction of complex queries and reduce the likelihood of human errors in the process.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const leads = await LeadsTable.findRecords({
  filter: AI`works either at ${workflow.company} OR is not in IT`,
  limit: 10,
  offset: 0,
})
```

The query is written inside the backticks (\`) that come after \`filter: AI\`. The AI expects a query string, and that's why backticks are used.

#### Re-using filters (selectors)

Selectors are filters that you can re-use. They don't have to be written again and again.

For example, you might use the query selector "People with age greater than 18" to find all users who are above 18.

1. Create a query selector in the table and give it a name. (for example: adults)
2. Add query as `People with age greater than 18`
3. use below code to find records and save it in a variable called `adults`

<YouTube />

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Find records in the table
const data = await Data1Table.findRecords({ selectorName: 'adults' })
workflow.adults = data
```

#### Difference between search and AI filters

A standard `Search` in Botpress is employed to identify specific strings like a user's name. It gives precision-based results by matching specific sets of characters.

On the other hand, an `AI Filter` broadens the scope and is used primarily for filtering results rather than explicitly searching them. It helps you track down users based on certain criteria, such as age above 25.

Although the AI Filter isn't primarily designed for exact string hunting, it's flexible enough to allow it. For instance, you could use it to filter results for `Canada` as a country.

### Get record

You can use the `getRecord` function to retrieve a specific record from a table based on a unique identifier. For example, you might use the `getRecord` function to retrieve a user's profile information based on their unique user ID.

<YouTube />

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// The record ID is 1 and User is the variable name
const data = await Data1Table.getRecord(1)
workflow.User = data
```

### Update record

You can use the `updateRecord` function to modify a specific record in a table. This will be useful when you need to update a specific field in the record. For example, you might use this function to update a user's profile information or to update the status of a transaction.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Update at record ID 8's Age to 45
await Data1Table.updateRecord(8, { Age: 45 })
```

### Upsert record

The `upsertRecords` function allows you to update or create records in a table in a single operation. It's useful for any situation where you need to update or insert data into a table without having to worry about whether the rows already exist.

**Example:**

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Update the name and address of the records with IDs 1 and 2.
await CustomersTable.upsertRecords('id', [
  { id: 1, name: 'John Doe', address: '123 Main Street' },
  { id: 2, name: 'Jane Doe', address: '456 Elm Street' },
])
```

This code will upsert the records into the CustomersTable. If the records with IDs 1 and 2 already exist in the table, the function will update the existing rows with the new name and address values. If the records with IDs 1 and 2 don't already exist in the table, the function will insert new rows into the table with the new name and address values.

## Computed Columns

Columns can be marked as "Computed" which allows the <Tooltip>bot builder</Tooltip> to observe changes in tables and generate computed values. This includes leveraging AI, as well as running code. This can be useful for a wide variety of use cases such as CRM enrichment, sentiment analysis, classification.

To use computed columns, simply create a column and toggle the **Computed** field as shown below.

<img />

### Selecting the basis of computation

To compute columns, you must select what information you will base your computed columns on. To do so, click the **Dependencies** field and select all column names that you will use.

<img />

In the above example, we selected a column called **number**.

### AI-based computed columns

You can perform AI text generation tasks by filling the prompt and including rows like this \{\{propertyName}}.

```
Come up with the title for a story like the three little pigs for the number {{number}}
```

In the above example, for the number 3, you might get "The Three Clever Squirrels" as a value in the cell.

### Code-based computed columns

To run arbitrary code, select the **Execute code** tab. Then, click **Edit Code**.

<img />

You will see a window with a code editor.

<img />

Simply add your code above. The proper syntax for accessing columns you've identified as dependencies is row\[propertyName], and the displayed cell value is what's returned by this function. You can call asynchronous functions within the function, and have the **Axios** library available to perform HTTP requests.

For instance, the following code will return the Fibonacci number of the row value for the column **number**.

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function fibonacci(n) {
  if (n <= 1) {
    return n
  }
  return fibonacci(n - 1) + fibonacci(n - 2)
}

if (!row.number) {
  return 0
}

return fibonacci(row.number)
```

There is currently an execution timeout of two minutes these.

### Updating computed values

To ensure computed values are always kept up to date, we recommend **Auto-compute** be toggled on.

<img />

If you don't have **Auto-compute** enabled, a grey icon will appear next to stale table cells.

<img />

To update the stale data, simply re-activate **Auto-compute**.

## Importing and Exporting

### Import a Table

You can import a table from a CSV file. Click on the `Import Table` button above the table and select the CSV file you want to import. Botpress will automatically detect the column names and types from the CSV file and create the table structure for you.

### Export a Table

Click on the `Export Table` button to export the table. This will download the table as a CSV file to your computer.

<Warning>
  Reminder

  Don't edit the CSV file directly to avoid data loss and import errors. Instead, make the changes in Botpress Studio and then export the updated table again.
</Warning>

<Note>
  Note

  When you export a bot, the tables are exported as well so there is no need to export them separately unless you want to use them in another bot.
</Note>


# Triggers
Source: https://botpress.com/docs/studio/concepts/triggers



Triggers are a special kind of [Node](/docs/studio/concepts/nodes) that only **execute when a certain event occurs**. You can recognize Triggers by their distinctive purple colour:

<Frame>
  <img alt="Trigger" />
</Frame>

Triggers are useful if you want your bot to:

* [Send a welcome message](#conversation-started)
* [Do something at a specific date/time](#fixed-schedule)
* [Respond to changes on your website](#custom-trigger)

<Warning>
  ### Limitations

  * Triggers won't work in the Studio's emulator, even when the event they're expecting occurs. Instead, you can [test them](#test-a-trigger) before publishing.
  * Triggers won't work while your bot is waiting for user input from a [Capture Information](/docs/studio/concepts/cards/capture-information) Card.
</Warning>

## Triggers vs. Nodes

Triggers are different from regular Nodes in a few ways:

* You **can't transition** from a regular Node to a Trigger. Any Triggers in your Workflow will only execute when the event they listen for occurs.
* Unlike other Nodes, **you can't add or remove [Cards](/docs/studio/concepts/cards)** from a Trigger. Each Trigger is built around a single Card that determines when it executes.

## Add a Trigger

To add a Trigger, just right-click anywhere in a Workflow:

<Frame>
  <img alt="Add a Trigger" />
</Frame>

## Test a Trigger

Triggers won't work in the Studio's emulator, even when the event they're expecting occurs. Instead, you can use a previous event to test your Trigger.

For example, to test the [Conversation Started](#conversation-started) Trigger:

<Steps>
  <Step title="Add the Trigger to your Workflow">
    Right-click anywhere in your Workflow. Select **Trigger**, then **Conversation Started**:

    <Frame>
      <img alt="Conversation Started" />
    </Frame>
  </Step>

  <Step title="Configure a test">
    Select **Test** in the bottom-left corner of the Trigger:

    <Frame>
      <img alt="Test Trigger" />
    </Frame>

    Then, select **Show last received events**. This will display a list of past events that would set off your Trigger:

    <Frame>
      <img alt="Test events" />
    </Frame>

    For the **Conversation Started** Trigger, each of these is a `conversationStarted` event, which fires every time a user starts a new conversation with your bot.

    You can use any one of these events as a dummy event to test your Trigger. Just pick one and select **Add as Test**. Then, select **Save**.

    <Note>
      If there are no events available to choose, make sure your bot is published and that the event your Trigger is listening for has occurred at least once before.
    </Note>
  </Step>

  <Step title="Test the Trigger">
    Now, you should see the name of the event in the Trigger:

    <Frame>
      <img alt="Fire Trigger" />
    </Frame>

    Just press the play icon to fire the Trigger. Any logic you have connected to the Trigger will execute in the emulator:

    <Frame>
      <img alt="Trigger fires in emulator" />
    </Frame>
  </Step>
</Steps>

## Webchat Triggers

Studio comes with some built-in Triggers that let your bot react to certain events in Webchat:

### Conversation Started

<Tip>
  For a step-by-step guide to the **Conversation Started** Trigger, check out the [Webchat documentation](/docs/webchat/interact/start-trigger).
</Tip>

The **Conversation Started** Trigger only executes when a user starts a new conversation in Webchat. You can use it to make your bot do something as soon as a user starts a new conversation.

For example, sending a welcome message:

<Frame>
  <img alt="Welcome message" />
</Frame>

### Custom Trigger

<Tip>
  For a step-by-step guide to using **Custom Triggers**, check out the [Webchat documentation](/docs/webchat/interact/send-custom-events/to-webchat).
</Tip>

You can use **Custom Triggers** to make Webchat react to custom events from your website. This is useful if you want to make your bot more responsive to the rest of your user experience.

For example, if you want your bot to respond when a user clicks a button:

<Frame>
  <img alt="Custom Trigger reacting to buttons" />
</Frame>

## Fixed Schedule

<Tip>
  Check out our step-by-step guide on [using the Fixed Schedule Trigger](/docs/studio/concepts/cards/fixed-schedule).
</Tip>

You can use the **Fixed Schedule** Trigger to execute some part of your Workflow at a specific time. This is useful if you want to send reminders, notifications, or other time-sensitive messages to users.

## Integrations

<Tip>
  Check out the [integrations section](/docs/integrations/) for information about integration-specific Triggers.
</Tip>

Some integrations include their own Triggers. When you install an integration that has Triggers, they'll become available in the Triggers menu.

For example, the [Zendesk integration](/docs/integrations/integration-guides/zendesk) comes with two Triggers—**Article Published** and **Article Unpublished**:

<Frame>
  <img alt="Zendesk Triggers" />
</Frame>


# Built-in variables
Source: https://botpress.com/docs/studio/concepts/variables/built-in



Botpress provides several **built-in variables** that contain useful information about the current state of your bot. You don't need to create these variables yourself—you can just read them whenever you need them.

Here's a list of all the built-in variables in Botpress:

| Path                                                                            | Type        | Description                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event.preview`                                                                 | Event       | The last message sent by the user. It will be replaced every time there is a new message.                                                                                                                                                                  |
| `conversation.SummaryAgent.summary`                                             | Agent       | Summary of the conversation created by the [Summary Agent](/docs/studio/concepts/agents/summary-agent). It's an explanation of what happened.                                                                                                                   |
| `conversation.SummaryAgent.transcript`                                          | Agent       | Transcript of the conversation going back a certain amount of turns.                                                                                                                                                                                       |
| `turn.KnowledgeAgent.answer`                                                    | Agent       | The answer provided by the [Knowledge Agent](/docs/studio/concepts/agents/knowledge-agent)                                                                                                                                                                      |
| `turn.KnowledgeAgent.responded`                                                 | Agent       | Whether the Knowledge Agent has responded automatically to a user question. Its value will be `true` or `false`                                                                                                                                            |
| `turn.KnowledgeAgent?.answer?.length`                                           | Agent       | The amount of characters in the Knowledge answer. Use this in an [Expression](/docs/studio/concepts/cards/flow-logic#expression) to check if there is an answer in the KB. Optionally add `!` to start of the code in order to check if there WASN'T an answer. |
| `turn.KnowledgeAgent.citations`                                                 | Agent       | A list of citations for the Knowledge answer.                                                                                                                                                                                                              |
| `user.TranslatorAgent.language`                                                 | Agent       | The current user language code in ISO 639-1 format. [More about the Translator Agent](/docs/studio/concepts/agents/translator-agent)                                                                                                                            |
| `user.TranslatorAgent.language = 'en'`                                          | Agent       | This code snippet set's the user language to English. Replace with any language code in the ISO 639-1 format                                                                                                                                               |
| `event.kb.results.map((a) => a.dsFriendlyName + '\n' + a.content).join('\n\n')` | Event       | This code snippet returns the raw content that generated the final Knowledge answer.                                                                                                                                                                       |
| `event.tags.conversation['whatsapp:userPhone']`                                 | Integration | The user's phone number on WhatsApp. Includes the international code.                                                                                                                                                                                      |
| `event.tags.conversation['whatsapp:phoneNumberId']`                             | Integration | The phone number ID of the bot on WhatsApp.                                                                                                                                                                                                                |


# Use variables in code
Source: https://botpress.com/docs/studio/concepts/variables/in-code



If you need more flexibility in how you handle information in Botpress Studio, you can use variables in code (for example, in an [Execute Code](/docs/studio/concepts/cards/execute-code) Card).

<Tip>
  Variables in code follow the pattern `variabletype.variablename`.
</Tip>

Here are a few examples of how you might use variables in code:

## Assign a value to a variable

This is typically how you'd initialize a variable or change its value.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
workflow.orderNumber = 12345
conversation.cartTotal = 59.99
user.lastName = 'Smith'
bot.version = '1.2.3'
env.databaseURL = 'https://example.com/db'
```

## Use variables in conditional statements

This checks the value of a variable and executes code accordingly.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (user.firstName === 'John') {
  console.log('Hello John!')
} else {
  console.log('Welcome, user!')
}
```

## Use variables in functions

Here, you might pass a variable as a function argument or use it inside a function.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function greetUser(firstName) {
  console.log('Hello, ' + firstName + '!')
}

greetUser(user.firstName)
```

## Combine variables

You might want to combine or concatenate variables.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
var fullName = user.firstName + ' ' + user.lastName

// or

var welcomeMessage = 'Hello, ' + user.firstName + ' ' + user.lastName + '!'
```

## Check variable types

Botpress might throw an error if types don't match. To avoid this, you can use type checking before assigning values.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (typeof workflow.userAcctId === 'number') {
  workflow.userAcctId = 67890
} else {
  console.error('Invalid type for userAcctId!')
}
```

## Use variables with external APIs

If your bot interacts with external services, you might use an environment variable to store an API key:

````javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const apiKey = env.API_KEY
const apiUrl = env.API_URL

const config = {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
}

const response = await axios.get(apiUrl, config)
const data = response.data

// Process the data as needed
// ...

// Example: Log the response data
console.log(data)
```                                                                                                                                                                                                  |
````


# Variables
Source: https://botpress.com/docs/studio/concepts/variables/overview

Containers for storing and reusing information in Botpress Studio.

Variables let you **store information** from somewhere in Botpress Studio and **reuse it somewhere else**.

<Tip>
  Think of a variable like an **empty box**. You can fill it with any kind of information you want—like a name, a number, or a preference—and put it away for safekeeping. Then, when your bot needs that information again, it can open the box and access what's inside.
</Tip>

## Variable scopes

You can use different types of variables to **scope** the information you store. This gives you control over where your bot can access a piece of information. For example, you might want some information to:

* [Follow a user across all their conversations](/docs/studio/concepts/variables/scopes/user) (for example, their name and address)
* [Persist only throughout a single conversation](/docs/studio/concepts/variables/scopes/conversation) (for example, items in a virtual cart)
* [Be safely accessible across all your bot's activity](/docs/studio/concepts/variables/scopes/configuration) (for example, API tokens and secrets)

Select any variable scope below to learn more about it:

<CardGroup>
  <Card title="Workflow variables" href="/studio/concepts/variables/scopes/workflow">
    Only available within the current Workflow
  </Card>

  <Card title="User variables" href="/studio/concepts/variables/scopes/user">
    Available for all conversations with a user
  </Card>

  <Card title="Conversation variables" href="/studio/concepts/variables/scopes/conversation">
    Only available within the current conversation
  </Card>

  <Card title="Bot variables" href="/studio/concepts/variables/scopes/bot">
    Available throughout all your bot's activity
  </Card>

  <Card title="Configuration variables" href="/studio/concepts/variables/scopes/configuration">
    Available throughout all your bot's activity, but can't be displayed to users
  </Card>
</CardGroup>

## Create a variable

<Note>
  Configuration variables have a different setup process. Check out the [configuration variables](/docs/studio/concepts/variables/scopes/configuration) page for more information.
</Note>

Before you can store information in a variable, you need to create it:

1. Open any Workflow.
2. Select **+** in the **Variables** section at the bottom of the left navigation bar.
3. Choose a [Scope](#variable-scopes), [Type](#data-types-for-variables) and **Name** for your variable:

<Frame>
  <img alt="Create a variable" />
</Frame>

<Note>
  By default, variables are empty when created. However, you can create them with a default value if you prefer—just specify a **Default Value** in the **Additional Settings** menu.
</Note>

### Assign a value to your variable

A freshly created variable is like an empty box—you need put something inside it before you can use it. This is called **assigning a value** to your variable.

Studio will usually indicate where you have the option to assign a value to a variable.. For example, in a [Capture Information](/docs/studio/concepts/cards/capture-information) Card:

<Frame>
  <img alt="Assign a value to a variable" />
</Frame>

<Tip>
  If you want more control over when and how you assign a value to a variable, you can [use code instead](/docs/studio/concepts/variables/in-code).
</Tip>

### Read your variable

When you need to access the information stored in a variable, you can **read** it. This is like opening the box and looking at what's inside.

Each variable scope is read differently. Check out the [section for your variable's scope](#variable-scopes) for more information.

## Data types for variables

Botpress variables are **typed**, meaning they're limited in what data they can hold. These data types are important to:

* Ensure the code behind Botpress runs smoothly
* Help AI tasks generate better results

Here are the different data types available for Botpress variables:

<table>
  <thead>
    <tr>
      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        String
      </td>

      <td>
        Values that are treated as text. Strings can contain any amount of letters, numbers, or special characters. <br /> <br /> Example uses: Storing a user's name, storing an AI task's generated message.
      </td>
    </tr>

    <tr>
      <td>
        Boolean
      </td>

      <td>
        Variables can be true or false, with a lowercase 't' or 'f'. <br /> <br />Example uses: Storing if a user is a returning customer, storing whether the bot has greeted the user or not
      </td>
    </tr>

    <tr>
      <td>
        Number
      </td>

      <td>
        Variables that are numeric, either with or without decimal places. <br /> <br />Example uses: Storing a user's phone number, storing an address's area code
      </td>
    </tr>

    <tr>
      <td>
        Date
      </td>

      <td>
        Variables that are a single date or date and time. Botpress uses ISO 8601 date/time format, such as `20220921T10:34:14` for `21 September 2023 at 10:34 AM` (with 14 seconds). <br /> <br />Example uses: Storing when the user starts a chat, storing a user's appointment date
      </td>
    </tr>

    <tr>
      <td>
        Object
      </td>

      <td>
        Variable that's a collection of key-value pairs. Useful when dealing with code and written like `{key: value}`. <br /> <br />Example uses: Storing a user's profile, storing the results of an API call
      </td>
    </tr>

    <tr>
      <td>
        Array
      </td>

      <td>
        Variable that's a collection of other, similar variables. Arrays can contain strings, like `[“a”, “b”, “c”]`, or Objects like `[{key:value},{key:value}]`. <br /> <br />Example uses: Storing a user's past messages, storing options for the user to choose from
      </td>
    </tr>

    <tr>
      <td>
        Enum
      </td>

      <td>
        Variable that can be one of a set number of choices. <br /> <br />Example uses: Storing days of the week, storing items available from a food menu
      </td>
    </tr>

    <tr>
      <td>
        Pattern
      </td>

      <td>
        Variable that uses Regular Expressions/Regex to store a special pattern. This pattern can match certain words or numbers.<br /> <br />Example uses: Storing account numbers, storing flight numbers
      </td>
    </tr>
  </tbody>
</table>


# Pass variables between Workflows
Source: https://botpress.com/docs/studio/concepts/variables/pass-between-workflows



You can pass variables between Workflows. This is useful if you want to use a previously created variable within the scope of a single Workflow. For example:

* You want to collect user information in one Workflow, then validate it in a sub-Workflow.
* You have a Workflow that stores items in a virtual shopping cart, and you want to process payment for those items in a sub-Workflow.
* You have some condition in one Workflow, and you want a sub-Workflow to behave differently based on that condition.

## From a parent Workflow to a sub-Workflow

<Steps>
  <Step title="Setup your input variable">
    1. In your sub-Workflow (the one you want to pass the variable to), [create a new Workflow variable](/docs/studio/concepts/variables/overview/#create-a-variable).

    <Note>
      You can pass any kind of variable from your parent Workflow, but your sub-Workflow needs to treat it as a Workflow variable.
    </Note>

    2. Select your sub-Workflow's [Entry Node](/docs/studio/concepts/nodes/introduction#entry-node).
    3. Under **Toggle Variables**, select the variable you just created:

    <Frame>
      <img alt="Toggle input variable" />

      <img alt="Toggle input variable" />
    </Frame>

    This tells the parent Workflow that your sub-Workflow is expecting some input.
  </Step>

  <Step title="Pass the variable to the sub-Workflow">
    In your parent Workflow, select the Card that transitions to the sub-Workflow. It should display the input variable you just created:

    <Frame>
      <img alt="Input variable field" />

      <img alt="Input variable field" />
    </Frame>

    You can manually enter a value to pass to the sub-Workflow, or use a previously created variable from your parent Workflow.

    <Check>
      Now, whatever value you pass from your parent Workflow will be available in your sub-Workflow as a Workflow variable.
    </Check>
  </Step>
</Steps>

## From a sub-Workflow to a parent Workflow

<Steps>
  <Step title="Pass your output variable">
    1. Select your sub-Workflow's [Exit Node](/docs/studio/concepts/nodes/introduction/#exit-node).
    2. Under **Toggle Variables**, select the variable you want to pass:

    <Frame>
      <img alt="Toggle output variable" />

      <img alt="Toggle output variable" />
    </Frame>

    This tells the parent Workflow to expect some output from the sub-Workflow.

    <Note>
      You can only pass Workflow variables from a sub-Workflow to a parent Workflow.
    </Note>
  </Step>

  <Step title="Configure the sub-Workflow Card">
    1. In the parent Workflow, select the Card that transitions to the sub-Workflow:

    <Frame>
      <img alt="Workflow Card" />

      <img alt="Workflow Card" />
    </Frame>

    2. Make sure the **Exit Nodes** option is selected.
  </Step>

  <Step title="Read the output variable in the parent Workflow">
    To access the sub-Workflow's output variable from within the parent Workflow, read:

    `workflow.<cardName>.<variableName>`

    <Frame>
      <img alt="Read output variable" />

      <img alt="Read output variable" />
    </Frame>

    <Check>
      Your parent Workflow now has access to its sub-Workflow's variable.
    </Check>
  </Step>
</Steps>


# Bot variables
Source: https://botpress.com/docs/studio/concepts/variables/scopes/bot



Bot variables let you store and reuse information **throughout your entire bot**.

Any information you assign to a bot variable will be accessible across all Workflows and conversations. This makes bot variables useful for storing global information about your bot, like:

* Your bot's name
* Your bot's version number
* Endpoints for your bot's API calls

<Warning>
  Bot variables aren't encrypted or stored securely. This means **an Autonomous Node can read and display any information you store in a bot variable**.

  Don't save sensitive information like API keys or passwords in bot variables—use [**configuration variables**](/docs/studio/concepts/variables/scopes/configuration) instead.
</Warning>

<Tip>
  Need help getting started with variables? Check out our [introduction to variables](/docs/studio/concepts/variables/overview).
</Tip>

## Read a bot variable

You can use `{{bot.variablename}}` or `@bot.variablename` to read a bot variable. For example, in a **Text** Card:

<Frame>
  <img alt="Bot variable in a text card" />
</Frame>


# Configuration variables
Source: https://botpress.com/docs/studio/concepts/variables/scopes/configuration



Configuration variables let you **securely store information throughout your bot**.

Like [bot variables](/docs/studio/concepts/variables/scopes/bot), configuration variables are accessible across all Workflows and conversations. The key difference is that configuration variables are **encrypted**. This means an Autonomous Node can't read or display information you store in a configuration variable.

This extra layer of security makes configuration variables great for storing sensitive information, like:

* API Tokens
* Private IP Addresses
* Usernames and passwords

<Note>
  If you need your variable to be available globally but don't need/want to store it securely, use a [bot variable](/docs/studio/concepts/variables/scopes/bot).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to variables](/docs/studio/concepts/variables/overview).
</Tip>

## Create a configuration variable

To create a configuration variable:

1. In the Studio, select **Bot Settings** from the bottom-left corner.
2. Scroll to the **Configuration Variables** section:

<Frame>
  <img alt="Configuration variables" />
</Frame>

3. Select **+**, then enter a **Name** and **Value** for your variable:

<Frame>
  <img alt="Configuration variable fields" />
</Frame>

## Read a configuration variable

You can use `env.variablename` to read a configuration variable. For example, in an [Execute Code](/docs/studio/concepts/cards/execute-code) Card:

<Frame>
  <img alt="Access configuration variable in an Execute Code Card" />
</Frame>


# Conversation variables
Source: https://botpress.com/docs/studio/concepts/variables/scopes/conversation



Conversation variables let you store and reuse information within the scope of **a single conversation**.

This makes them great for storing information that's only relevant to the current conversation, but that you need to access in multiple Workflows. For example:

* Items in a virtual shopping cart
* Conversation-specific preferences
* A checklist to track the completion of sub-Workflows

<Note>
  Information stored in conversation variables is deleted when the current conversation is over. If you need a variable to persist across multiple conversations, use a different [variable scope](/docs/studio/concepts/variables/overview#variable-scopes).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to variables](/docs/studio/concepts/variables/overview).
</Tip>

## Read a conversation variable

You can use `{{conversation.variablename}}` or `@conversation.variablename` to read a conversation variable. For example, in a **Text** Card:

<Frame>
  <img alt="Conversation variable in a text card" />
</Frame>


# User variables
Source: https://botpress.com/docs/studio/concepts/variables/scopes/user



User variables let you store and reuse information within the scope of **a single user**.

Any information you assign to a user variable will follow the user across multiple conversations with your bot. This makes user variables great for storing user-specific information, like:

* Personal details
* User preferences
* Notes from previous conversations

<Note>
  If you don't want your variable to follow the user between conversations, use a different [variable scope](/docs/studio/concepts/variables/overview#variable-scopes).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to variables](/docs/studio/concepts/variables/overview).
</Tip>

## Read a user variable

You can use `{{user.variablename}}` or `@user.variablename` to read a user variable. For example, in a **Text** Card:

<Frame>
  <img alt="User variable in a text card" />
</Frame>


# Workflow variables
Source: https://botpress.com/docs/studio/concepts/variables/scopes/workflow



Workflow variables let you store and reuse information within the scope of **a single [Workflow](/docs/studio/concepts/workflows)**. They're great for:

* Storing an AI task's output
* Saving and reusing user input
* Organizing data returned from an API call

<Note>
  Workflow variables are only accessible in the Workflow they were created in. If you need a variable to be accessible in multiple Workflows, use a different [variable scope](/docs/studio/concepts/variables/overview#variable-scopes).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to variables](/docs/studio/concepts/variables/overview).
</Tip>

## Read a Workflow variable

You can use `{{workflow.variablename}}` or `@workflow.variablename` to read a Workflow variable. For example, in a **Text** Card:

<Frame>
  <img alt="Workflow variable in a text card" />
</Frame>


# Versions
Source: https://botpress.com/docs/studio/concepts/versions

View, compare, and revert to previous versions of your bot.

Versions in Botpress help you track, manage, and control changes made to your bots.

They provide a detailed log of updates, allowing you to view past versions, compare changes, and revert to previous states if necessary. This feature is essential for collaborative bot development, ensuring transparency, accountability, and easy recovery from unintended changes.

## Accessing Versions

The Versions menu can be found on the left-hand menu by clicking on the icon that looks like a clock.

## Creating a new Version

Versions are created in two ways:

1. By clicking on the '+' in the Versions menu and manually creating a new Version
2. Automatically, every time you publish your bot

It's a good idea to annotate every saved Version you have and indicate any of the major changes or updates made.

## Reverting to a previous Version

From the Versions menu, you can revert to a previous version by clicking into it and restoring to a previous Version. Note that reverting to a previous version will completely overwrite your current bot, including any unsaved changes you may have made.

Botpress can't restore lost or overwritten bot Versions.

<Note>
  Note

  Pay-as-you-go users have access to 3 saved Versions.

  Team Plan subscribers have access to 15 saved Versions.
</Note>


# Workflows
Source: https://botpress.com/docs/studio/concepts/workflows



<Icon icon="workflow" /> Workflows are **sequences of steps that your bot takes**:

<Frame>
  <img alt="Workflow" />

  <img alt="Workflow" />
</Frame>

Each Workflow represents a reusable, customizable section of your bot's logic. You can use them to organize your bot's behaviour. For example, you might want to:

* Greet users and offer assistance
* Validate a user response
* Collect personal data before checking out

Instead of having the logic for each of these tasks in one big sequence, you can put each one in its own Workflow. Then, just [transition](#transition-to-a-workflow) to whichever Workflow you need.

***

## Overview

Workflows are made up of [Nodes](/docs/studio/concepts/nodes/) that determine their behaviour. You can modify the Nodes within a Workflow by dragging and dropping them.

Every Workflow you create has at least two Nodes:

* An **Entry Node** that executes whenever you transition to the Workflow
* An **Exit Node** which exits the current Workflow and returns to its parent Workflow

You can put any amount of Nodes in between these two—they'll execute in order when you transition to the Workflow.

<Note>
  You can [pass data between Workflows](/docs/studio/concepts/variables/pass-between-workflows)—check out the
  [variables](/docs/studio/concepts/variables/) section for more information.
</Note>

***

## Built-in Workflows

Every bot comes with a few built-in Workflows to handle specific situations gracefully:

<Frame>
  <img alt="Default Workflows" />

  <img alt="Default Workflows" />
</Frame>

You can modify the contents of each one to suit your needs. Here's a breakdown of each default Workflow.

### Main

The Main Workflow is the entry point for every conversation with your bot. It executes every time a new conversation begins:

<Frame>
  <img alt="Main Workflow" />

  <img alt="Main Workflow" />
</Frame>

Unlike custom Workflows, the Main Workflow always contains:

* A [Start Node](/docs/studio/concepts/nodes/introduction#start-node) that starts the conversation
* An [End Node](/docs/studio/concepts/nodes/introduction#end-node) that ends the conversation

### Error

The Error Workflow executes when there's an unexpected error in one of your other Workflows. You can use it to inform the user that something went wrong:

<Frame>
  <img alt="Error Workflow" />

  <img alt="Error Workflow" />
</Frame>

Instead of an **Exit** Node, the Error Workflow contains an **End** Node. This ensures that the conversation ends after the error occurs.

### Timeout

The Timeout Workflow executes after a period of prolonged inactivity from the user. You can use it to inform the user that the conversation timed out:

<Frame>
  <img alt="Timeout Workflow" />

  <img alt="Timeout Workflow" />
</Frame>

Instead of an **Exit** Node, the Timeout Workflow contains an **End** Node. This ensures that the conversation ends after the timeout occurs.

<Tip>You can set a custom timeout delay in your [Bot Settings](/docs/studio/concepts/bot-settings).</Tip>

### Conversation End

The Conversation End Workflow executes right before the conversation ends explicitly. You can use it to summarize the conversation before it ends, or offer follow-up actions:

<Frame>
  <img alt="Conversation End" />

  <img alt="Conversation End" />
</Frame>

Instead of an **Exit** Node, the **Conversation End** Workflow contains an **End** Node. This ensures that the conversation ends after the Workflow executes.

<Note>
  The **Conversation End** Workflow only executes before the conversation ends explicitly—that is, when a Workflow transitions to an [End Node](/docs/studio/concepts/nodes/introduction#end-node).

  Since Autonomous Nodes don't transition to an End Node when the user ends the conversation, they won't transition to the Conversation End Workflow by default.
</Note>

***

## Add a Workflow

To add a new Workflow, navigate to the **Workflows** menu in Studio:

<Frame>
  <img alt="Workflows section" />

  <img alt="Workflows section" />
</Frame>

Then, select **Create Workflow** and enter a name for the new Workflow:

<Frame>
  <img alt="New Workflow" />

  <img alt="New Workflow" />
</Frame>

### From Botpress Hub

You can also browse [Botpress Hub](/docs/integrations/get-started/botpress-hub) for user-uploaded Workflows and add them to your bot. Just filter by Workflow to see all available Workflows:

<Frame>
  <img alt="Workflows on Hub" />

  <img alt="Workflows on Hub" />
</Frame>

To add any Workflow, select it, then select **Install Workflow**.

<Tip>
  To edit a Workflow you installed from Botpress Hub, you need to make a copy of it within your bot. After installing,
  select **Make a copy and Edit**—the Workflow will then open in Studio.
</Tip>

***

## Transition to a Workflow

Any Workflows you add are available as a [Card](/docs/studio/concepts/cards/) from the **Flow Logic** section of the Card tray:

<Frame>
  <img alt="Flow Logic" />

  <img alt="Flow Logic" />
</Frame>

To transition to a new Workflow, just add it to the Node you want to transition from:

<Frame>
  <img alt="Transition Card" />

  <img alt="Transition Card" />
</Frame>

***

## Group Workflows in folders

You can group Workflows into folders to keep them organized:

<Frame>
  <img alt="Workflow folders" />

  <img alt="Workflow folders" />
</Frame>

Just select **Add Folder** in the Workflows menu to create a new folder. Then, you can drag any Workflows (or sub-folders) you want into the folder.

***

## Share a Workflow

You can share any Workflow you create on [Botpress Hub](/docs/integrations/get-started/botpress-hub) to make it available to other users. Just select **Share Workflow** <Icon icon="external-link" /> in the upper-right corner of the Workflow and fill out the required fields.


# State Management
Source: https://botpress.com/docs/studio/guides/advanced/best-practices-for-state-management

Manage the 128 KB state size limit in Botpress by optimizing Workflows, clearing unused variables, and minimizing large data usage.

## Overview

Efficient state management is crucial for optimizing bot performance in Botpress. This guide outlines best practices to avoid performance degradation and errors caused by exceeding the **128 KB state size limit**, ensuring your bot operates seamlessly.

***

## Understanding State Size Limits

Botpress enforces a **state size limit of 128 KB** to maintain optimal performance. Poorly managed state variables, especially in nested Workflows, can lead to:

* **State bloat**: Accumulation of unnecessary or oversized variables.

* **Performance issues**: Slower bot responses as state size grows.

* **Errors**: Logs showing state size limit exceeded.

***

## Avoiding Common Workflow Design Pitfalls

### Workflow Structure and State Retention

How Workflows are designed impacts the state management. Consider two scenarios:

### Scenario 1: Proper Workflow Exit

* **Workflow 1** ends completely before transitioning to **Workflow 2**.

* Variables from Workflow 1 are cleared upon exit, keeping the state clean.

**Example:**

Workflow 1 → **End** → Workflow 2 → **End**

<img />

### Scenario 2: Improper Workflow Exit

* **Workflow 1** transitions directly into **Workflow 2** without exiting.

* Variables from Workflow 1 persist until **Workflow 3** finishes, causing state size to increase unnecessarily.

**Example:**

Workflow 1 → Workflow 2 → Workflow 3 → **End**

<img />

***

## Best Practices for State Management

### 1. Design Workflows with Proper Exits

Ensure that each Workflow completes before initiating the next. This prevents unused variables from lingering in the state.

**Best Practice Workflow Design:**

Workflow 1 → End

Workflow 2 → End

### 2. Manually Clear Unused Variables

In scenarios where restructuring Workflows is impractical, manually clear state variables to manage size effectively.

**Implementation Tips:**

* Remove variables that are no longer needed by setting it to null value or by reusing it.

### 3. Minimize Use of Large Variables in Main Workflow

Avoid storing large data structures (e.g., arrays, objects) in the main Workflow (`wf-main`). Instead, limit variables to essentials for transitions or core logic.

**Best Practices:**

* Move non-essential or large variables to sub-Workflows.

* Use modular Workflows for better management.

### 4. Monitor and Audit State Size

Regularly inspect and optimize state size to identify potential issues early.

**Tools and Techniques:**

* Use Botpress debugging tools to examine `variable_values`.

* Audit Workflow designs periodically to ensure compliance with best practices.

***

## Optimizing Nested Workflow Designs

Nested Workflows can be efficient but require careful handling to avoid state retention issues. Follow these strategies:

1. **Plan Transitions Carefully**: Design clear entry and exit points for each Workflow.

2. **Use Modular Sub-Workflows**: Break Workflows into smaller, task-specific components.

3. **Limit Parent Variable Retention**: Clear parent Workflow variables when transitioning to nested Workflows.

***

## Conclusion

Adhering to these state management best practices ensures your bot performs optimally, avoids the **128 KB state size limit**, and maintains clean and efficient Workflows:

1. Design Workflows with proper exits.

2. Manually clear unused variables when needed.

3. Minimize use of large variables in the main Workflow.

4. Regularly monitor and audit state size.

By implementing these guidelines, you’ll enhance bot performance, reduce errors, and provide a better user experience.


# Event Properties
Source: https://botpress.com/docs/studio/guides/advanced/event-properties



<ResponseExample>
  ```json Event properties theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  {
    "botId": "<string>",
    "conversationId": "<string>",
    "createdOn": "<Date>",
    "direction": "<EventDirection>",
    "id": "<string>",
    "integration": "<string>",
    "kb": {
      "included": [],
      "results": []
    },
    "messageId": "<string>",
    "payload": {},
    "preview": "<string>",
    "state": {},
    "tags": {
      "conversation": {},
      "message": {},
      "user": {}
    },
    "trigger": {
      "conversationId": "<string>",
      "eventName": "<string>",
      "flowId": "<string>",
      "integration": "<string>",
      "nodeId": "<string>",
      "userId": "<string>"
    },
    "type": "<string>",
    "userId": "<string>"
  }
  ```
</ResponseExample>

Whenever an event occurs during your bot's execution—like a message being sent—you can access details about that event using the `event` object's properties.

The `event` object is available [wherever you can use code in Botpress Studio](/docs/studio/guides/advanced/use-code). This includes:

* [Hooks](/docs/studio/concepts/hooks)
* [Actions](/docs/studio/concepts/actions)
* [Execute Code Cards](/docs/studio/concepts/cards/execute-code)

You can also access the `event` object within certain [Cards](/docs/studio/concepts/cards/introduction)' configuration fields.

<Warning>
  This documentation omits certain properties of the `event` object which exist to maintain internal functionality and aren't useful for <Tooltip>bot builders</Tooltip>.
</Warning>

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string">
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date">
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="EventDirection">
      The direction of the event, indicating whether the event was received by the bot or sent from the bot.

      Possible values:

      * `'incoming'`: The event originated from the user and was received by the bot.
      * `'outgoing'`: The event was generated by the bot and sent to the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/docs/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/docs/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="Studio.KnowledgeBase.KB[]">
          Array of Knowledge Bases queried for the event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="Studio.KnowledgeBase.ContentResult[]">
          Array of Knowledge Base results consulted for this event.

          <Warning>
            Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string">
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="EventState">
      Data related to the state of the event.

      <Warning>
        Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/docs/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string">
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string">
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>


# Accessing The Autonomous Nodes Thought Process
Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/analyze-llmz-responses

Analyze Knowledge Base responses from Autonomous Nodes in Botpress with the “After LLMz Execution” hook.

Capture metrics like query content, response source, and user context for precise insights into Knowledge Base interactions and improved bot performance.

<Note>
  Note

  If you are looking to simply understand a response in the emulator, you can use the inspect button to get information about the Autonomous nodes thinking. But for other use cases, Botpress allows you to create a JavaScript hook that allows you do something with the data programmatically.
</Note>

## Using LLMz hooks

Sometimes you want to do something with that information in your production bots, perhaps for analytics, perhaps for figuring out issues. LLMz hooks allow you to do that. You can use them to monitor and analyze responses from LLMz-powered Autonomous Nodes, especially when they retrieve information from the Knowledge Base (KB), and you can send the information to a Botpress Table, or to your preferred analytics tool.

You can follow the [Botpress guide](/docs/studio/guides/advanced/exporting-data/streaming-analytics-from-within-your-bot-with-hooks) for setting up streaming analytics for messages, but if you'd like to get information on LLMz logic, you can follow these steps to adjust for this.

### Step 1: Setting Up Your Analytics Tool

Start by configuring your analytics tool to capture data from your Botpress bot. Refer to your tool’s documentation to obtain any necessary API keys or project identifiers.

Likewise, if you'd like to use Botpress Analytics, or Botpress Tables, you can also do so.

### Step 2: Configuring the "After LLMz Execution" Hook

The **After LLMz Execution** hook can be set up to collect data whenever an Autonomous Node retrieves and responds with information from the Knowledge Base. This hook is triggered each time the node generates a response, enabling you to capture KB interactions.

To set up this hook:

1. Navigate to the **Hooks** tab in **Botpress Studio**.
2. Click **Create Hook** and select the **After LLMz Execution** hook.

This hook function provides access to two key parameters:

* `event`: The [Event object](/docs/studio/guides/advanced/event-properties) with details about the interaction.
* `execution`: An object containing data on the LLMz execution, including details of each iteration and response content. More information on the `execution` object structure is provided [below](#the-execution-object).

## Example Code for the After LLMz Execution Hook

The code below demonstrates how to capture analytics data when an Autonomous Node references information from the Knowledge Base.

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Only execute if Knowledge Base requests were made
if (event?.kb?.results?.length) {
  const botAnalyticsData = {
    // Timestamp of the event
    time: event.createdOn.getTime(),
    // Unique identifiers
    $insert_id: event.id,          // Prevents duplicate events
    distinct_id: event.userId,     // Identifies unique users
    bot_id: event.botId,
    conversation_id: event.conversationId,
    // Knowledge Base interaction data
    query: event.preview,          // User's query to the Knowledge Base
    result: event?.kb?.results[0].content,  // Matching KB content fragment
    fileName: event?.kb?.results[0].title,  // Source document name

    // Bot response data - formatted message sent to user
    autonomousNodeResponse: execution.iterations[execution.iterations.length - 1].message,

    // Context information
    current_flow: event.state.context.currentFlow,
    current_node: event.state.context.currentNode,
    current_card: event.state.context.currentCard
  }

  // Replace with your analytics tool's API endpoint
  const projectToken = '<your_analytics_token>'
  await axios.post(
    '<analytics_tool_endpoint>',
    [{
      event: 'Outbound Message',
      properties: botAnalyticsData,
    }],
    {
      headers: {
        Authorization: `Basic ${btoa(projectToken + ':')}`,
      },
    }
  )
}
```

### The `execution` Object

The `execution` object provides detailed information about the actions taken by the Autonomous Node, specifically capturing each iteration and its outcome. This includes messages sent, code executed, signals received, and more. Here’s an in-depth look at its structure and contents:

### Structure of `execution` Object

* `status`: String indicating the overall status of the execution, e.g., `"success"`, `"partial"`, `"failure"`.

* `iterations`: Array of objects, each representing a step or interaction in the Autonomous Node’s execution. Each iteration contains:
  * `message`: The text response generated at this stage.
  * `code`: Code executed during this iteration, often in response to specific queries.
  * `variables`: Object holding variables used within the iteration.
  * `status`: Status of the individual iteration, e.g., `"partial"`, `"success"`.
  * `signal`: Information on any signals received, often in the form of structured `ThinkSignal` or other signals, detailing contextual reasoning.
  * `started_ts`: Timestamp (in milliseconds) indicating when the iteration started.
  * `ended_ts`: Timestamp (in milliseconds) when the iteration concluded.
  * `llm`: Object detailing the large language model used, including its version and parameters.
  * `mutations`: Array of any mutations or transformations applied to variables.
  * `traces`: Trace data related to the LLM's decisions and actions.
  * `messages`: Messages used or processed within this step.
  * `notebook`: Object representing any generated or stored notebook content for reference.

* `context`: Contains settings, variables, and tools relevant to the execution:
  * `__options`: Execution settings such as the model version, number of loops, temperature, and specific instructions.
  * `transcript`: Transcript of messages exchanged, with each entry detailing user and bot interactions.
  * `getMessages`: Function for retrieving messages, typically used internally for processing.
  * `partialExecutionMessages`: Array holding messages generated if the execution is paused or partially completed.
  * `tool_names`: Names of tools used in the execution, e.g., APIs or functions.
  * `iteration`: Current iteration count in the execution loop.
  * `injectedVariables`: Variables introduced during execution, such as results from Knowledge Base queries.

* `location`: Provides information about the Autonomous Node’s current position in the Workflow:
  * `type`: Indicates whether it's a Workflow or standalone operation.
  * `workflowId`: Unique identifier for the Workflow.
  * `workflowName`: Name of the Workflow where the execution takes place.
  * `nodeId`: Identifier for the specific node within the Workflow.
  * `nodeName`: Name of the node, e.g., `"AutonomousNode"`.


# Compiled Bot Analytics
Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/exporting-compiled-bot-analytics-with-the-botpress-api



The Botpress Cloud dashboard provides you with an Analytics page with counters for the total number of users, new users, returning users, sessions and messages. It also shows a chart with the data and allows you to filter by date range.

While this interface is great for understanding reach and engagement in a glance, you may need the data in a third-party service. Luckily, you can use the Botpress API to export the analytics data to your own database or system. Let's see how to do it.

## Making a request to the API

Send a `GET` request to `https://api.botpress.cloud/v1/admin/bots/<your-bot-id>/analytics` adding the following header: `Authorization: Bearer <your-personal-access-token>`.

<Note>
  Note

  You can find your personal access token in your [Botpress Dashboard](https://app.botpress.cloud/). Click your avatar and select "Personal Access Tokens". Generate a new one and copy it.
</Note>

This is how the request would look like using Axios in a JavaScript application:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const requestConfig = {
  headers: {
    Authorization: `Bearer ${process.env.BOTPRESS_PERSONAL_ACCESS_TOKEN}`,
  },
}

const getAnalytics = await axios.get(`https://api.botpress.cloud/v1/admin/${botId}/analytics`, requestConfig)
```

If you were to print the analytics (available at `getAnalytics.data.records`), the result would look like this:

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[
  {
    "startDateTimeUtc": "2023-10-18T00:00:00.000Z",
    "endDateTimeUtc": "2023-10-30T20:00:00.000Z",
    "returningUsers": 14,
    "newUsers": 4,
    "sessions": 4,
    "messages": 146
  },
  {
    "startDateTimeUtc": "2023-09-01T03:00:00.000Z",
    "endDateTimeUtc": "2023-09-31T19:00:00.000Z",
    "returningUsers": 38,
    "newUsers": 16,
    "sessions": 25,
    "messages": 1943
  }
]
```

<Note>
  Note

  It's a list of records containing the start and end date of the period, the number of returning users, new users, sessions and messages. With this information you can create your own charts and dashboards in your internal systems or favorite BI tool.
</Note>

If you need advanced analytics about user behavior and the paths they take when interacting with the bot, you can use the [Hooks method](/docs/studio/concepts/hooks) to export the data in real-time to a third-party service like Mixpanel, Hotjar, Segment or Amplitude.


# Raw Conversations
Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/exporting-raw-conversations-with-the-botpress-api



The Botpress API allows you to access your bot's conversations from an external service. This is very useful if you need to manage or analyze the conversations somehow. In this tutorial we give steps to use the API for this purpose and steps to format the response data. Let's get started!

<Note>
  Note

  Access the API documentation to verify the schema/structure of the [Conversations and Messages](/docs/get-started/manage-your-agent/monitor#conversations) and see if the data is useful for your use case.
</Note>

<Note>
  Note

  You can find your personal access token in your [Admin Dashboard](https://app.botpress.cloud/). You can find your bot ID in the URL of your bot's dashboard, it's the letters and numbers right after `chatbots/`
</Note>

## 1. Getting the Conversations list from the API

### Using Axios

Send a `GET` request to `https://api.botpress.cloud/v1/chat/conversations` adding the following headers: `Authorization: Bearer <your-personal-access-token>` and `x-bot-id: <your-bot-id>`.

This is how the request would look like using Axios in a JavaScript application (e.g in a Execute Code in Botpress):

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const requestConfig = {
  headers: {
    // Authorization header with a Bearer token for authentication.
    Authorization: `Bearer ${process.env.BOTPRESS_PERSONAL_ACCESS_TOKEN}`,
    // The unique identifier of the bot for which we want to retrieve conversations.
    'x-bot-id': process.env.BOTPRESS_BOT_ID,
  },
}

// An empty array to store all retrieved conversations.
const allConversations = []

// Send an HTTP GET request to the specified API endpoint to get conversations.
const getConversations = await axios.get(
  `https://api.botpress.cloud/v1/chat/conversations?nextToken=${paginationToken}`,
  requestConfig
)

// Add the retrieved conversations to the list.
allConversations.push(...getConversations.data.conversations)
```

### Using the Botpress Client library

The same logic to get conversations but using the [Botpress Client library](https://www.npmjs.com/package/@botpress/client) in a Node.js application:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Client } from '@botpress/client'

const client = new Client({
  token: process.env.BOTPRESS_ACCESS_TOKEN,
  botId: process.env.BOTPRESS_BOT_ID,
})

const allConversations = []

const getConversations = await client.listConversations({
  nextToken: paginationToken,
})

allConversations.push(getConversations.conversations)
```

<Info>
  Info

  The API returns a maximum of 20 conversations per request. You will need to use the `nextToken` property to fetch the next batch of conversations. The `nextToken` property is returned in the `meta` object of the response.
</Info>

## 2. Getting all Conversations from the API

Now that you know the methods of getting the first conversations from the API, let's see how to get them. You can get them gradually or all at once, but you need to use the [pagination](/docs/api-reference/pagination) token regardless.

### Getting conversations gradually

Create a function that will fetch the next batch of conversations when called. You could use a button to trigger it or trigger it automatically with infinite scroll. Pass the `nextToken` property retrieved from the first request as a parameter to the function, then update it on subsequent calls.

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
async function loadConversations(paginationToken) {
  const getConversations = await axios.get(
    `https://api.botpress.cloud/v1/chat/conversations?nextToken=${paginationToken}`,
    {
      ...requestConfig,
    }
  )

  return getConversations.data
  // The returned value will be an object: `{ conversations: [...], meta: { nextToken: "string" } }`
}
```

### Getting all conversations

Use a loop to fetch all conversations at once using the above logic. This isn't recommended for bots with a large number of conversations as it may take a long time to complete and may cause timeouts. The use of a library like\
[p-retry](https://www.npmjs.com/package/p-retry) to retry requests automatically is recommended.

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const allConversations = []
let paginationToken

do {
  // Send an HTTP GET request to the specified API endpoint to get conversations.
  const getConversations = await axios.get(
    `https://api.botpress.cloud/v1/chat/conversations?nextToken=${paginationToken}`,
    requestConfig
  )

  // Add the retrieved conversations to the list.
  allConversations.push(...getConversations.data.conversations)

  // Retrieve the token for the next set of conversations, if available.
  paginationToken = getConversations.data.meta.nextToken

  // As long as paginationToken has a value, this function will execute again
} while (paginationToken)
```

## 3. Getting the Messages list

Once you have gone through the list of conversations and found out the id of the desired conversation to export, you can then use the API to list the actual messages.

In the example below we're using the [Botpress Client library](https://www.npmjs.com/package/@botpress/client) and assume the client is set up already:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const conversationId = 'the desired conversation id here'

const allMessages = []

const getMessages = await client.listMessages({
  conversationId,
  nextToken: paginationToken,
})

allMessages.push(getMessages.messages)
```

You might create a loader function or a finite loop as shown above to get all the messages.\
This is how the `allMessages` array is gonna look like:

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[
  {
    "id": "503dda87-3e54-40b6-8167-55d685a85345",
    "createdAt": "2023-10-24T20:20:44.812Z",
    "conversationId": "ec669jj8-e465-482d-8fbe-cb348bf81212",
    "payload": {
      "text": "Pick one or many from the list",
      "options": [
        {
          "label": "First option",
          "value": "First option"
        },
        {
          "label": "Second option",
          "value": "Second option"
        }
      ]
    },
    "tags": {},
    "userId": "efc0f8e8-7e51-4458-8907-ea1e43eb8852",
    "type": "choice",
    "direction": "outgoing"
  },
  {
    "id": "41bb8564-e7ab-4113-c3d8-5fdhh27e4c34",
    "createdAt": "2023-10-24T20:20:49.201Z",
    "conversationId": "ec66ffb8-e465-482d-8fbe-csd348b81212",
    "payload": {
      "type": "quick_reply",
      "text": "First option",
      "payload": "First option"
    },
    "tags": {
      "webchat:id": "cc70c21b-4g24-4f5c-8f52-43a900b7b047"
    },
    "userId": "f96da97d-4215-447f-86e2-b9e33232e6d3",
    "type": "quick_reply",
    "direction": "incoming"
  },
  {
    "id": "c6ee8bd6-c862-54d2-97cb-998f555d4251",
    "createdAt": "2023-10-24T20:20:49.795Z",
    "conversationId": "ec669dd8-e465-482d-8fty-cb3348581212",
    "payload": {
      "imageUrl": "https://s3.us-east-1.amazonaws.com/cloud-studio-botsbca2d219-2316w6llinepa/f4b77ea0-d597-4d3f-988d-9c66f127d542/media/2360a7bb-162b-4ed1-8551-7000fdb0f7ef.png"
    },
    "tags": {},
    "userId": "efb454t5-7e51-4458-8007-ea1e43eb8852",
    "type": "image",
    "direction": "outgoing"
  }
]
```

<Note>
  Note

  In this example the bot sends a Multiple Choice card, then the user answers by clicking one of the options, and then the bot sends an Image card. Notice how the message payload changes according to the message type, so be mindful of that when reading the `payload` property.
</Note>

## 4. Formatting the Messages list

Now that you have the list of messages of a conversation it's time to format it so it becomes readable. We're going to use a custom function for that:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function formatMessage(message) {
  let messageText = ''

  if (message.direction === 'incoming') {
    messageText += 'User: '
  } else {
    messageText += 'Bot: '
  }

  if (message.type === 'text' || message.type === 'quick_reply') {
    messageText += message.payload.text
  } else if (message.type === 'choice') {
    messageText += `${message.payload.text}: ${message.payload.options.map((option) => option.label).join(' / ')}`
  } else {
    messageText += `Media message of type ${message.type}`
  }

  messageText += `\n at ${new Date(message.createdAt).toLocaleString()}`

  return messageText
}

const history = allMessages.map((message) => formatMessage(message)).join('\n\n')
```

The `history` string will end up looking like this:

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Bot: Pick one or many from the list: First Option / Second Option
at 24/10/2023, 5:20:44 PM

User: First Option
at 24/10/2023, 5:21:00 PM

Bot: Media message of type image
at 24/10/2023, 5:21:09 PM
```

<Note>
  Note

  You can customize the `formatMessage` function to have different formatting or to return more information of the messages. Now use the `history` variable however you like - send it via email, add it to a Google Sheets document, send it to Botpress to do further processing, etc.
</Note>


# Conversation History
Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/getting-the-conversation-history-from-within-your-bot



Botpress Cloud provides you with several different ways to export a conversation to external services, each one has its use cases and advantages. Let's take a look at them.

## Using the Summary Agent

The [Summary Agent](/docs/studio/concepts/agents/summary-agent) listens to all new messages in the conversation to build a summary and a transcript.

* The summary is available at `conversation.SummaryAgent.summary` and contains an explanation of what happened in conversation, like "The user asked for the opening hours and the bot answered by saying the business works 24/7". You can choose how detailed the summary is by setting the max tokens in the Agent settings.
* The transcript is available at `conversation.SummaryAgent.transcript` and contains the history of the conversation going back a certain amount of turns. You can set that amount of turns in the Summary Agent settings. If you set it to 0, the transcript will contain all messages.

### Advantages

The `summary` variable is useful if you don't need to have many details about the conversation, especially because some of them get lengthy and if you may not want all that data. The `transcript` variable is the best way to have the full history of the conversation in a single text without needing [Hooks](/docs/studio/concepts/hooks) or other workarounds. Using the Summary Agent for exporting conversations is also great because you have access to the history during the very conversation so you don't need to make manual or scheduled requests to our API from external services.

### Disadvantages

The disadvantage of using the Summary Agent for exporting conversations is that after the amount of messages surpasses the max amount of turns for the transcript, you won't have the full conversation anymore (You can mitigate this by setting the max amount to 0). Another disadvantage is that the Agent only has access to the\
current session, so if the user is resuming a conversation, you won't have the previous messages in the history. To get the whole conversation at any moment, use the [API method for exporting conversations](/docs/studio/guides/advanced/exporting-data/exporting-raw-conversations-with-the-botpress-api)

## Using Hooks

[Hooks](/docs/studio/concepts/hooks) are functions that are executed under the hood every time there's a new message from the user or from the bot. You can create hooks that build the conversation history as it happens. They work similarly to the Summary Agent but with hooks you can customize how the history is built and there's no limitation for its size (with the exception of the 128KB max session size).

### Advantages

This solution is useful if you need to have all details about the conversation. It also allows you to build the history however you like - adding more information than only the message and actor.

### Disadvantages

The disadvantage of using Hooks is that it requires some work to set up and you only have access to the current session, so if the user is resuming a conversation, you\
won't have the previous messages in the history. To get the whole conversation at any moment, use the [API method for exporting conversations](/docs/studio/guides/advanced/exporting-data/exporting-raw-conversations-with-the-botpress-api)

### Setting up the Hooks

1. Create a hook under "Before Incoming Message" in the "Hooks" section with the following code:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (!event.state.session.fullHistory) {
  event.state.session.fullHistory = ''
}
event.state.session.fullHistory = event.state.session.fullHistory + `user:  ${event.payload.text}` + '\n'
```

2. Create a hook under "Before Outgoing Message" with the following code:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if (!event.state.session.fullHistory) {
  event.state.session.fullHistory = ''
}
event.state.session.fullHistory = event.state.session.fullHistory + `bot: ${outgoingEvent.payload.text}` + '\n'
```

## Sending the Conversation History

Now that you have the conversation history, you can add an [Execute Code card](/docs/studio/concepts/cards/execute-code) to manipulate the variable as you prefer, for example sending it to an API or via email:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await axios.post('https://my-api-url.com', {
	// keep only the desired variable below
	conversation: event.state.session.fullHistory OR conversation.SummaryAgent.summary OR conversation.SummaryAgent.transcript
	user: user.name
})
```

<Info>
  Info

  You could add this card to the [Conversation End](/docs/studio/concepts/workflows#conversation-end) Workflow so that the full session is sent when the conversation ends. (The bot will only enter the End Workflow if there's an explicit Transition to an End node)
</Info>


# Exporting Data
Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/introduction

Export data from your bot using the Botpress API by requesting the relevant endpoint.

Botpress Cloud allows you to create, manage, and deploy bots with little to no coding or infrastructure. In the natural course of maintaining a bot you may want to access its data outside of Botpress for various purposes, such as reporting, analysis, backup, or integration.

This section covers some of the most important use cases for extracting bot data to third-parties software.

<table>
  <thead>
    <tr>
      <th>
        **Action**
      </th>

      <th>
        **Methods**
      </th>

      <th>
        **Use Cases**
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Exporting conversations
      </td>

      <td>
        [Using the Botpress API](./exporting-raw-conversations-with-the-botpress-api)
      </td>

      <td>
        Data Analysis\
        Compliance and Auditing\
        Backup and Historical Record\
        Debugging
      </td>
    </tr>

    <tr>
      <td>
        Exporting analytics
      </td>

      <td>
        [Using the Botpress API](./exporting-raw-conversations-with-the-botpress-api)
      </td>

      <td>
        Performance Monitoring and Evaluation\
        User Tracking and Behavior Analysis\
        Product Management\
        Debugging
      </td>
    </tr>
  </tbody>
</table>


# Streaming Analytics
Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/streaming-analytics-from-within-your-bot-with-hooks



The Botpress Cloud dashboard provides you with an Analytics page with counters for the total number of users, new users, returning users, sessions and messages. It also shows a chart with the data and allows you to filter by date range.

While this interface is great for understanding reach and engagement in a glance, you may need more in-depth data about user behavior and the paths they take when interacting with the bot, and you may need to have this data streamed to a third-party service like Hotjar, Segment or Amplitude. Luckily, you can use the Hooks feature to do just that!.

In this tutorial we're going to use Mixpanel as an example, but you can use any service that has a REST API and an endpoint to receive events.

## Setting up Mixpanel

1. Create an account and a project in [Mixpanel](https://mixpanel.com/).
2. Go to your project settings and copy the Project Token.

## Setting up the Hooks

1. Open Botpress Studio, go to the Hooks tab and click on the `+` button next to **Before Incoming Message** to create a new hook.
2. Name it `send-user-analytics` for example
3. Add the following JavaScript code:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const userAnalyticsData = {
  time: event.createdOn.getTime(), // Mixpanel event datetime
  $insert_id: event.id, // Mixpanel unique event
  distinct_id: event.userId, // Mixpanel preventing duplicates
  bot_id: event.botId,
  conversation_id: event.conversationId,
  payload: event.payload,
  text: event.preview,
  current_flow: event.state.context.currentFlow,
  current_node: event.state.context.currentNode,
  current_card: event.state.context.currentCard,
}

const projectToken = '<your token>'

await axios.post(
  'https://api.mixpanel.com/import',
  [
    {
      event: 'Inbound Message',
      properties: userAnalyticsData,
    },
  ],
  {
    headers: {
      Authorization: `Basic ${btoa(projectToken + ':')}`,
    },
  }
)
```

4. Click on the `+` button next to **Before Outgoing Message** to create a new hook.
5. Name it `send-bot-analytics` for example
6. Add the following JavaScript code:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const botAnalyticsData = {
  time: outgoingEvent.createdOn.getTime(), // Mixpanel event datetime
  $insert_id: outgoingEvent.id, // Mixpanel unique event
  distinct_id: outgoingEvent.userId, // Mixpanel preventing duplicates
  bot_id: outgoingEvent.botId,
  conversation_id: outgoingEvent.conversationId,
  payload: outgoingEvent.payload,
  text: outgoingEvent.preview,
  current_flow: outgoingEvent.state.context.currentFlow,
  current_node: outgoingEvent.state.context.currentNode,
  current_card: outgoingEvent.state.context.currentCard,
}

const projectToken = '<your token>'

await axios.post(
  'https://api.mixpanel.com/import',
  [
    {
      event: 'Outbound Message',
      properties: botAnalyticsData,
    },
  ],
  {
    headers: {
      Authorization: `Basic ${btoa(projectToken + ':')}`,
    },
  }
)
```

<Note>
  Note

  Now every time a user or the bot sends a message, Mixpanel will be notified with the event data. You can use this data to create funnels, analyze user behavior and understand the paths they take when interacting with the bot.
</Note>


# Advanced Starter Template
Source: https://botpress.com/docs/studio/guides/advanced/kitchen-sink-advanced-starter-template



## Import Guide

1. Go to the [Advanced Starter Template](https://github.com/botpress/growth/tree/master/advanced-starter-bot-template) located on the Botpress Growth Team's GitHub!
2. Scroll down to the "How to use" section and click the download link for the [kitchen-sink.bpz](https://github.com/botpress/growth/blob/master/advanced-starter-bot-template/kitchen-sink.bpz) file.
3. Click on the download icon on the right side of the screen (see screenshot below).

<img />

4. Go to your [Botpress studio](https://studio.botpress.cloud)
5. Click on the Botpress icon at the top left of your screen
6. Click "Import / Export" and then click on "Import from file" (see screenshot below).

<img />

7. Select this template!
8. Enjoy!!! Please make sure to read the rest of this documentation and watch the video below!

## Purpose

This comprehensive template covers the core features and capabilities of Botpress, serving as both a learning resource and a foundation for your bot projects.

Whether you are new to Botpress or looking to explore our features, this template provides practical, real-world examples you can learn from and adapt to your needs. Follow along with our YouTube tutorial below for a detailed walkthrough of all the features.

<YouTube />

## Core Functionalities

1. **Initial User Data Loading**
   * Capture platform-specific user data (Messenger ID, WhatsApp number, Webchat data, etc...)
   * Handle different integration sources
2. **Event Tracking**
   * Custom analytics platform integration
   * Support for Google Analytics, Mixpanel, and Segment
   * Botpress' built-in analytics Agent.
3. **Proactive Greeting**
   * Bot-initiated conversations (embedded Webchat and shareable link only)
4. **Workflow Routing System**
   * Using a central routing node to route to other Workflows.
   * Helps solve the question "How to transition outside of an autonomous node?"
   * Two routing options:
     1. Autonomous node-based routing (AI option)
     2. Button-based routing (non-AI option)
5. **Requiring Information from the User to Send to an External Tool**
   * Required field collection (for example: requiring a valid email)
   * External tool to send tickets or information to
   * Botpress table integration (to send information as rows)
6. **Querying Knowledge Base and Saving Search Results**
   * Question and answer tracking
   * Prevent AI hallucinations by telling the user that no answer was found if the information doesn't exist within the Knowledge Base. This bot covers fallback handling for unanswered questions.
   * Track the exact chunk, Knowledge Base, and citation for where the information came from within your Knowledge Base.
7. **Live Agent Handoff**
   * Assigning a ticket to a live agent, causing the conversation with the bot to be temporarily paused until the live agent is done solving the ticket.
   * The human can "talk through" the bot to the user.
8. **CSAT (Customer Satisfaction) System**
   * End-of-conversation survey
   * Conversation summary generation and storage in Conversation Ratings Table
9. **Table Search and Filtering**
   * Querying from a Botpress table to fetch row(s) based on user input parameters.
10. **Management of Multiple Sub-Bots within a Single Bot for Multi-Client Purposes**

* Client-specific Knowledge Base segmentation
* Customer tag and identity management
* Dynamic Knowledge Base selection
* Multi-client support within a single bot instance


# Retention Period
Source: https://botpress.com/docs/studio/guides/advanced/retention-period



The retention period for your Botpress data depends on its type:

| **Data type**                                                         | **Retention period**                                                                                            | **Notes**                                                                                        |
| :-------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| [Logs](/docs/studio/concepts/debugger-logs-json#logs)                      | 30 days                                                                                                         |                                                                                                  |
| [Conversations](/docs/get-started/manage-your-agent/monitor#conversations) | 90 days                                                                                                         | Can be manually deleted using the [Chat API](/docs/api-reference/chat-api/openapi/deleteConversation) |
| [Messages](/docs/get-started/manage-your-agent/monitor#conversations)      | 90 days                                                                                                         | Can be manually deleted using the [Chat API](/docs/api-reference/chat-api/openapi/deleteMessage)      |
| [Events](/docs/get-started/manage-your-agent/inspect#events)               | 90 days                                                                                                         |                                                                                                  |
| Files                                                                 | Indefinitely, unless [created with an expiry date](/docs/api-reference/files-api/openapi/upsertFile#body-expires-at) | Can be manually deleted using the [Files API](/docs/api-reference/files-api/openapi/deleteFile)       |

<Note>
  Other types of data are kept indefinitely unless you [delete them using one of our APIs](/docs/api-reference/).
</Note>


# Brand Safety Framework
Source: https://botpress.com/docs/studio/guides/advanced/safety/brand-safety-framework

Control AI responses, enforce brand-aligned messaging, and prevent harmful outputs.

The Brand Safety Framework in Botpress is a comprehensive suite of features designed to provide transparency and control over AI-driven decisions, ensuring brand safety across all interactions. Similar to a car's safety features—such as airbags and crash collision ratings—the framework isn't a single toggle but a holistic approach that includes several powerful tools designed to give you visibility into and control over an LLM's actions. Botpress empowers you with unparalleled insight into the logic of LLMs and equips you with the controls to adjust and refine decision-making processes, securing brand integrity in every interaction.

## LLM Transparency

Traditional LLMs and providers often operate as opaque black boxes, making it challenging to understand the reasoning behind their decisions. Botpress’s BSF addresses this challenge by exposing the decision-making pathways of LLMs, allowing users to see why certain outputs were generated and how they align with brand standards. The core principle is simple: when you can understand and influence an LLM’s decisions, you can protect your brand.

## Key Features

### Policy Agent

<img />

The Policy Agent is a rules-based mechanism that controls the outputs of LLMs by enforcing constraints and guardrails. By configuring policies, users can dictate acceptable response behaviors, prevent harmful outputs, and ensure that AI actions align with brand values.

##### Usage

* Define constraints, including YAML or JSON configurations.
* Set gates to filter out undesirable responses based on specific keywords, patterns, or context cues.
* Identify policies or behaviors your agent should adhere to during conversations.

### RAG Safety

<img />

Retrieval-Augmented Generation (RAG) Safety provides transparency over the data selection process used by LLMs. It reveals which data chunks were identified as relevant to a query and which were ultimately submitted to the LLM. Users have the ability to review, approve, or modify these selections, ensuring that only the most appropriate data informs the AI's output.

##### Usage

* Access a visual interface that displays selected chunks with contextual relevance scores.
* Modify data chunk selections manually or set up automated rules to refine data retrieval criteria.
* Log and audit the data flow to track the decisions made during the query process.

### LLM Inspector

<img />

The LLM Inspector is a tool that breaks down the decision-making process of the LLM, showing why it selected certain actions or responses. By dissecting the LLM’s internal logic, users can gain insights into the decision pathways and make informed adjustments to align AI behavior with brand standards.

##### Usage

* Inspect decision trees that outline response logic and action selection.
* View confidence scores, logic paths, and influence factors contributing to specific outputs.
* Adjust weighting and influence factors to steer future decision-making processes

### HITL

<img />

HITL, or Human-in-the-Loop, allows you to participate in an AI agent's conversation directly from the Botpress dashboard. This feature offers a critical layer of oversight and control when using LLMs in customer- or user-facing interactions. It was designed to ensure that sensitive or high-risk conversations can be escalated to human agents, helping maintain brand integrity, mitigate potential issues, and protect user privacy.

##### Usage

You can use HITL to define rules or "gates" within a conversation that determine when a human agent should intervene. For example, if the conversation involves sensitive personal data, triggers specific legal language, or moves into territory that may require human expertise, the conversation is automatically handed off to a human agent for further handling.

You can configure the system to identify specific keywords, scenarios, or actions that require human oversight. This level of customizability ensures that only relevant conversations are escalated, preserving efficiency while safeguarding privacy.

By integrating HITL into your LLM-driven solutions, you ensure your brand remains compliant with privacy standards, while retaining the flexibility and efficiency of AI-driven interactions.

This feature allows businesses to have the best of both worlds: leveraging cutting-edge AI to handle the bulk of interactions, while having the safety net of human oversight in sensitive situations. HITL enhances trust by allowing businesses to demonstrate that they're taking proactive steps to ensure conversations are handled responsibly. This creates confidence in the platform's ability to handle customer interactions without compromising privacy or brand safety.


# Safety
Source: https://botpress.com/docs/studio/guides/advanced/safety/introduction

Botpress provides a robust feature set that ensure AI-driven interactions are safe, controlled, and compliant.

Ensuring the safety of AI-driven interactions is a core priority for our team, and for <Tooltip>bot builders</Tooltip>. The Botpress platform is designed to empower developers while maintaining strict safety standards, giving you the tools needed to build reliable and controlled AI solutions. This overview covers the key safety aspects of Botpress, including constraint management, data privacy, access control, and mitigation of AI-related risks like hallucinations.

## Key Safety Features

1. **Policy Agent**: Control AI behavior with predefined rules and constraints to ensure responses align with your organization’s standards. The Policy Agent acts as a gatekeeper, enforcing guardrails and mitigating hallucinations by filtering outputs against customizable policies.

2. **Access Control & Permissions**: Secure your environment with granular access control. Define roles and permissions to regulate who can view, edit, and deploy AI models, ensuring that only authorized users can make changes.

3. **Data Privacy & Security**: Botpress prioritizes data security with encryption, anonymization, and secure API connections. Our platform helps you comply with privacy regulations, safeguarding sensitive information across all interactions.

4. **Monitoring & Analytics**: Gain insights into AI behavior and performance through monitoring and analytics tools. Track usage patterns, detect anomalies, and adjust policies in real time to maintain optimal safety levels.

5. **Error Mitigation & Recovery**: Implement fallback mechanisms that catch errors or misbehaviour, redirecting interactions to human agents or predefined safe states. This ensures continuity and reliability even when the AI is uncertain or encounters edge cases.

### **Why Safety Matters**

Building trust in AI systems starts with safety. By implementing robust safety measures, Botpress ensures your AI solutions aren't only effective but also secure and compliant with industry standards. Our commitment to safety helps you deploy AI with confidence, knowing that you are in control of every interaction.


# Preventing Abuse
Source: https://botpress.com/docs/studio/guides/advanced/safety/preventing-abuse



At Botpress, we prioritize the security and integrity of your bots by implementing a range of robust measures to counteract fraud and malicious usage. Our strategy includes:

### Rate Limits&#x20;

Rate limits serve as a fundamental safeguard for your bot's resources. Each bot is assigned a maximum rate of messages it can process per second. For users on the "Team" plan, a higher rate limit is applied. Enterprise customers can further customize these limits to align with their specific requirements.

Rate limiting prevents the excessive influx of messages, ensuring that your bot operates efficiently and consistently. This is an essential component of our abuse prevention strategy.

### Allowed Origins&#x20;

Allowed Origins is a feature that lets you explicitly control where your bot is allowed to run by specifying a whitelist of approved domains. When deploying your bot on a website, you include only the domains that you trust, and the system automatically blocks any attempts to embed the bot from unapproved sources. This straightforward, security-first approach not only minimizes the risk of unauthorized use but also aligns with best practices for maintaining a secure, controlled deployment environment.

### Web Application Firewall (WAF)

Our Web Application Firewall, often referred to as WAF, is a powerful layer of defense against various cyber threats. WAF can protect your bot from Distributed Denial of Service (DDoS) attacks, SQL injection, cross-site scripting, and many other malicious activities.

By using WAF, Botpress takes advantage of AWS's robust security mechanisms, which are detailed in [AWS WAF Documentation](https://docs.aws.amazon.com/waf/latest/developerguide/ddos-responding.html). This means that your bot is shielded from a wide range of web-based threats, allowing it to perform at its best without disruption.

### Billing Limits

To provide an additional layer of protection, you have the ability to set monthly spending limits. This feature ensures that even if an abuse attempt were to circumvent the rate limits and WAF, your financial exposure remains under control. By defining a spending limit, you can prevent unexpectedly high bills resulting from excessive bot usage.

In summary, our abuse prevention strategy combines rate limits, WAF protection, and billing limits to keep your bots safe and efficient. This multi-faceted approach is designed to mitigate potential abuse scenarios and maintain the integrity of your bot's operation.

<Info>
  Info

  You can watch the [Usage tab](/docs/get-started/configure-your-workspace#track-usage-quotas) in the Admin Dashboard to continuously verify the usage of Botpress computational resources by your bot, ensuring that it's operating within the expected limits.
</Info>


# Tips to optimize AI Cost
Source: https://botpress.com/docs/studio/guides/advanced/tips-to-optimize-ai-cost



## Caching AI Responses

Caching is one of our most effective strategies to cut bots’ AI costs. By caching AI responses, we reduce the number of requests to the LLM provider which can reduce the cost of queries by approximately 30% saving you money without compromising the quality of interactions of the bot with your users.

## Optimize your Knowledge Bases

Optimizing your Knowledge Bases (KBs) can greatly influence your AI Spend since KBs are usually the biggest AI cost driver in a Botpress project.

**Tip 1: Choose the Right AI Model**\
The choice of an AI model significantly impacts cost. Since GPT-3.5 Turbo is faster & cheaper than GPT-4 Turbo, we recommend thoroughly testing your setup with GPT-3.5 Turbo before considering an upgrade to more advanced versions.

Our KB Agent hybrid mode offers an excellent middle ground, as we initially use GPT-3.5 Turbo to attempt a response to a query and escalate to GPT-4 Turbo only if necessary.

**Tip 2: Shield Your KB**\
You can reduce your AI Spend by shielding your KB from unnecessary typical FAQs that don’t need AI or smart answering with a Find Records card. This is how it works: if you know that users typically ask one question and you have 50 well-known questions with their answers, you can add them to a table and query that table using a Find Records card. In case you don’t find an answer, only then should you look in a KB.

**Tip 3: Properly Scope your KBs**\
Depending on the type of information and the quantity of information that you want to add to a KB, it's usually best practice to do two things in parallel to cut AI Spend cost. First, organize your information into smaller KBs, with each KB scoped to a specific product/feature/topic. Second, drive the user through a Workflow with multiple questions to scope down your search to a specific KB; this won't only reduce the cost, but it will also yield better results.

**Tip 4: Website KB Data Source vs Search the Web KB Data Source**\
If you use a website as your KB data source but don’t make constant changes to the website that need to be reflected to your bot in real time then a good cost effective alternative is to use the Search The Web as your KB data source instead of the Website KB data source. Before making that transition, make sure to test that the performance on the questions you anticipate being asked isn't degraded with this switch.

**Tip 5: Query Tables with Find Records or Execute Code card**\
If you have a Table with data you want to query, consider using the Find Records card instead of using the Table in a KB. For those with technical expertise, executing code can be an even more cost-efficient method of querying a Table. You do so by querying the Table directly from the Execute Code card and storing the output in a Workflow variable that you can refer to later.

**Tip 6: Control The Chunks**\
By chunks I'm referring to the number of chunks that will be retrieved from the Knowledge Base to generate an answer. Generally the more chunks retrieved, the more accurate the answer—but it will take longer to generate and cost more AI tokens. Experiment with chunk size to establish the lowest amount that still leads to accurate responses.

## Use Execute Code Card to lower AI Spend cost

The Execute Code card can be a suitable, cost-effective replacement for some AI cards. Here are a few scenarios where you can consider using them:

**Smarter Message Alternatives**\
If you want your bot to send a different AI response for the same query every single time, you must prevent caching (see Appendix to learn how). There are scenarios where the increase in AI Spend can be justified by the improvement to the conversation experience. But this isn’t always the case.

Think of something like a simple greeting that’s generated with LLMs. With each greeting you will incur an additional AI Spend cost. Is it worth it? Probably not. Fortunately, there’s a cost-effective workaround: use an array with multiple responses and a simple function to randomly fetch a value and present it.

Depending on the conversation volume, the amount you save by implementing this method can be well worth the effort.

**Code Execution for Simple Tasks**\
For simple tasks, such as data reformatting or extracting information from structured data, using the Execute Code card can be more efficient, cheaper and faster than relying on an LLM.

**Alternatives to Summary Agent**\
You can use Execute Code cards to create your own transcript. Place an Execute Code card wherever you want to track the users’ and bot’s message in an array variable. Afterwards, you can use that array and feed it as context to your KB.

**Simplify When Possible**\
Opt for the simpler interaction method that accomplishes the same goal without degrading user experience. For example, if you’re interested in collecting user feedback a simple star rating system with comments will be more cost-effective than using AI to collect the same information.

## Tips for AI Tasks, AI Generate Text, and Translations

**Choose the Right AI Model**

Choosing the right AI model is so important that it’s worth mentioning twice. Similar to KBs, the choice of an AI model significantly impacts cost when it comes to AI Tasks. Opt for GPT-3.5 Turbo for less complicated instructions. Before considering an upgrade to more advanced versions, thoroughly test your setup with this model. Remember, GPT-4 Turbo costs 20x more than GPT-3.5 Turbo. Unless the results are considerably better, opt for GPT–3.5 Turbo.

In addition to the above, you can also conserve AI Spend by reducing the number of tokens consumed in each AI Task run.

Our recommendation is to be conscious about decreasing this number because it will result in any additional tokens to be truncated. For example, if you limit the length to 2000 tokens and your prompt plus your output is more than 2000 tokens, then your input will be truncated accordingly.

**AI Task vs AI Generate Text**\
For simple text outputs, the AI Generate Text card uses fewer tokens and is easier to set up than the AI Task card. For tasks involving parsing information, the AI Task card outperforms the AI Generate Text card.

Therefore, our recommendation is to use the AI Task card when you want to use AI to process information (for example: if you want to detect the user’s intention or if you want the AI to analyze the input). But, if you want to leverage AI to generate text, then use the AI Generate Text card instead (for example: if you want to take a KB answer and expand it or if you want to generate a question creatively).

**Translations**\
If your bot is going to be handling a high amount of multilingual conversations, consider integrating hooks with external translation services for a more cost-effective option.

## How to Prevent Caching

If you want to overcome caching to always get live results, you can do either of the following options:

For more permanent caching prevention: add `And discard:{{Date.now()}}` in all your AI-related cards (e.g., in the AI Task prompts, in the KB context, etc.).\
For temporary caching prevention: publish your bot and test it from an incognito window.

Note: all things being equal, by removing this caching layer and not making any other changes to your bot, the AI Spend cost will increase.


# Using code in Studio
Source: https://botpress.com/docs/studio/guides/advanced/use-code



You can **write custom code to interact with your bot programmatically** in many areas of Botpress Studio.

<Tip>
  Wherever you write custom code in Studio, you can access the [event object's properties](/docs/studio/guides/advanced/event-properties) to get information about the last event in your bot's operation.
</Tip>

## Language

You can use [TypeScript](https://www.typescriptlang.org) or regular [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) for custom code.

## Where you can use code

Depending on your needs, you have a few options on where to write code in Studio. Here's a cheat sheet:

| Option                                                    | Executes                                                                                                           | Reusable | Example                                                                       |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------- |
| [Actions](/docs/studio/concepts/actions)                       | When an [Autonomous Node](/docs/studio/concepts/nodes/autonomous-node) decides to (based on the conversation's context) | ✅        | Make an API call to a weather service whenever the user asks for the weather  |
| [Execute Code Cards](/docs/studio/concepts/cards/execute-code) | At a specific point in a [Workflow](/docs/studio/concepts/workflows)                                                    | ❌        | Perform a one-time operation on some data provided by a user                  |
| [Hooks](/docs/studio/concepts/hooks)                           | At a specific stage of the bot's operation                                                                         | ✅        | Every time a bot responds, add the total AI spend for its response to a table |

Check out each section below for a more detailed breakdown:

### Actions

[Actions](/docs/studio/concepts/actions) are reusable code snippets that only [Autonomous Nodes](/docs/studio/concepts/nodes/autonomous-node) can use.

Use Actions when:

* You need to execute a piece of code more than once
* You want AI to decide when to execute your code

### Execute Code Cards

[Execute Code Cards](/docs/studio/concepts/cards/execute-code) execute a one-time piece of code at some point in a [Workflow](/docs/studio/concepts/workflows). They're not reusable and can't be added to an Autonomous Node.

Use Execute Code Cards when:

* You only need to execute a piece of code in one place
* You want complete control over when the code executes

### Hooks

[Hooks](/docs/studio/concepts/hooks) execute code at specific stages of your bot's operation, like before every user message or after every conversation ends. They operate separately from your bot's conversational logic—when you create a Hook, it always executes at the same stage, no matter what changes you make to your Workflow.

Use Hooks when:

* You need to execute a piece of code every time your bot reaches a certain stage of its operation
* You need access to information about the Autonomous Node's iteration or the current turn's metadata

## Libraries

The following libraries come pre-installed in the Studio's code editor:

| Name                                                                | Description                                                                               | Usage                             |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------- |
| [Axios](https://axios-http.com/docs/intro)                          | HTTP client for making API requests.                                                      | Available globally as `axios`     |
| [Lodash](https://lodash.com)                                        | Utility library for data manipulation.                                                    | Available globally as `_`         |
| [Luxon](https://moment.github.io/luxon/#/)                          | Library for date/time manipulation.                                                       | Available globally as `luxon`     |
| [`botpress/client`](https://www.npmjs.com/package/@botpress/client) | Official Botpress HTTP client to query the [Botpress API](/docs/api-reference/introduction).   | Available globally as `client`    |
| [`bpinternal/zui`](https://www.npmjs.com/package/@bpinternal/zui)   | A fork of [Zod](https://zod.dev) with additional features.                                | Available globally as `z` / `zui` |
| [`botpress/zai`](https://www.npmjs.com/package/@botpress/zai)       | Botpress utility library that uses AI to manipulate and generate Zui schemas and objects. | Available globally as `zai`       |

<Warning>
  You can't import external libraries into the Studio's code editor.
</Warning>


# Botpress v12 (and self-hosted versions)
Source: https://botpress.com/docs/studio/guides/advanced/v12



<Warning>
  Botpress v12 **has been officially sunset** and is no longer available for purchase, download, or new deployments. This includes all other self-hosted or locally installed versions of Botpress (including those available for Microsoft Windows and other platforms),
</Warning>

## Existing customers

Current customers with active Botpress v12 subscriptions remain fully supported. If you are an existing customer and have questions about your subscription or deployment, please reach out directly to your dedicated account manager for assistance.

## Moving forward with Botpress Cloud

All new users should use [Botpress Cloud](https://app.botpress.cloud), the fully managed web application, which represents the future of the Botpress platform. Botpress Cloud provides continuous improvements, security, and scalability without the need for local installation or maintenance.

## FAQ

<AccordionGroup>
  <Accordion title="Can I still download Botpress v12 or a self-hosted version?">
    No. Botpress v12 and all self-hosted versions are no longer available for download, purchase, or new deployments.
  </Accordion>

  <Accordion title="I am an existing Botpress v12 customer. What does this mean for me?">
    You remain fully supported. Please contact your dedicated account manager for any questions regarding your subscription or deployment.
  </Accordion>

  <Accordion title="What should I use now if I want to build with Botpress?">
    All new development should be done in [Botpress Cloud](https://app.botpress.cloud).
  </Accordion>
</AccordionGroup>


# Use different LLM for Autonomous Nodes
Source: https://botpress.com/docs/studio/guides/how-to/different-an-models



<Warning>
  You can now [override default LLMs directly in your Autonomous Node's settings](/docs/studio/concepts/nodes/autonomous-node#override-default-models).

  This method is simpler and recommended for most use cases. The guide below remains available for advanced use cases.
</Warning>

You can configure [Autonomous Nodes](/docs/studio/concepts/nodes/autonomous-node) to use a different LLM than the default model specified in your [Bot Settings](/docs/studio/concepts/bot-settings#autonomous-language-model). This is useful if your bot needs a higher-performing model for certain tasks.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [Workflow](/docs/studio/concepts/workflows) containing more than one Autonomous Node
  * Familiarity with JavaScript
</Info>

## Step 1: Find the Node, Workflow and model IDs

First, you need to find:

* The ID of the Autonomous Node whose model you want to change
* The ID of the Workflow containing that Autonomous Node
* The ID of the model you want to change to

### Node and Workflow IDs

1. Start a conversation with your bot in the [Emulator](/docs/studio/concepts/emulator).
2. Continue until the bot transitions to the Autonomous Node whose model you want to change:

<Frame>
  <img alt="Transition to new Autonomous Node" />

  <img alt="Transition to new Autonomous Node" />
</Frame>

3. Select one of your messages from after the bot transitioned to the new Autonomous Node. Then, open the [JSON tab](/docs/studio/concepts/debugger-logs-json#json) in the bottom panel.
4. Under **Payload**, navigate to `state > context`:

<Frame>
  <img alt="Current Workflow and Node IDs" />

  <img alt="Current Workflow and Node IDs" />
</Frame>

5. Copy the values of `currentFlow` and `currentNode`—these are your Workflow's ID and Autonomous Node's ID.

### Model ID

1. Return to your conversation in the Emulator.
2. Select **<Icon icon="search-code" /> Inspect** on any message generated by the Autonomous Node whose model you want to change.
3. Select **View Raw <Icon icon="braces" />** in the upper-right corner.
4. Navigate to `context > options > models`.
5. Find the model you want to switch to. Expand it, then copy its full `id`. For example, for GPT-4.1:

<Frame>
  <img alt="GPT 4.1" />

  <img alt="GPT 4.1" />
</Frame>

## Step 2: Add a Hook to change models

1. In the Studio, navigate to the <Icon icon="anchor" /> [Hooks](/docs/studio/concepts/hooks) section.
2. Select **Create Hook** and set its type to [Before LLMz Execution](/docs/studio/concepts/hooks#before-llmz-execution).
3. Paste the following code into the Hook:

```js highlight={6-7, 15} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Get the current Workflow and Node IDs
const flowID = event?.state?.context?.currentFlow ?? ''
const nodeID = event?.state?.context?.currentNode ?? ''

// Check if they match the ones we're targeting
const flowMatches = (flowID.includes('yourWorkflowID')) // Replace with your own
const nodeMatches = (nodeID.includes('yourNodeID')) // Replace with your own

console.log('Current model: ', context.model)
console.log('Current Workflow: ', flowID.toUpperCase())
console.log('Current Node: ', nodeID.toUpperCase())

// Switch models if they match
if (flowMatches && nodeMatches) {
  context.model = 'yourModelChoice' // Replace with your desired model
  console.log('Switched to ', context.model)
}
```

* Replace `yourWorkflowID` and `yourNodeID` with [your actual IDs](#node-and-workflow-ids).
* Replace `yourModelChoice` with the [actual model ID](#model-id).

<Check>
  Now, this Autonomous Node will use a different model than the default model specified in your [Bot Settings](/docs/studio/concepts/bot-settings#autonomous-language-model).
</Check>

## Troubleshooting

Here are some troubleshooting tips:

### State is undefined

If the `state` property from [Step 1](#node-and-workflow-ids) is `undefined`, make sure you're viewing your own message's logs—not the Autonomous Node's.

### Check if IDs matched

You can check if the Node and Workflow IDs matched by checking your bot's [logs](/docs/studio/concepts/debugger-logs-json) after transitioning to the Autonomous Node in the Emulator:

<Frame>
  <img alt="Model change logs" />

  <img alt="Model change logs" />
</Frame>

### Check if model actually changed

To check if the model actually changed:

1. Select **<Icon icon="search-code" /> Inspect** on any response from the target Autonomous Node.
2. Select **View Raw <Icon icon="braces" />** in the upper-right corner.
3. Navigate to `context > options > model`. This will display model the Autonomous Node used for the response.


# Send options as a dropdown menu
Source: https://botpress.com/docs/studio/guides/how-to/dropdown-menus



You can present options as a dropdown instead of buttons. This guide covers the built-in behaviour with [Capture Information](/docs/studio/concepts/cards/capture-information) and an approach using code when you need a dropdown with fewer than six options.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * Familiarity with JavaScript if you use [method 2](#method-2-manual-dropdown-execute-code)
</Info>

<Warning>
  The approach and styling in this guide are designed to work with [Webchat](/docs/webchat/get-started/quick-start)'s choice components. If your bot is deployed on a different channel, you may need to modify the approach to work with that channel's components. Check out the [integrations](/docs/integrations/get-started/introduction) section for more information.
</Warning>

## Method 1: Automatic dropdown (Capture Information)

1. Add a [Capture Information](/docs/studio/concepts/cards/capture-information) Card to your [Workflow](/docs/studio/concepts/workflows). Set the field type to **Single Choice** or **Multiple Choice**
2. Add your options inside the Card under **Choices**.

If you add more than five options, they are shown as a dropdown (list) instead of buttons. (The exact threshold can vary slightly by channel. See [Choices](/docs/studio/concepts/cards/capture-information#choices) on the Capture Information page.)

This is the simplest approach when you have enough options to trigger the dropdown UI.

## Method 2: Manual dropdown (Execute Code)

To show a dropdown even when you have five or fewer options, or to build the option list in code, send a message with `type: 'dropdown'` from an [Execute Code](/docs/studio/concepts/cards/execute-code) Card.

### Send the dropdown message

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await client.createMessage({
  userId: event.botId,
  conversationId: event.conversationId,
  tags: {},
  type: 'dropdown',
  payload: {
    text: 'Select an item:', // Shown above the control
    options: [
      { label: 'Dropdown 1', value: 'dd1' },
      { label: 'Dropdown 2', value: 'dd2' },
    ],
  },
})
```

1. **`payload.text`**: Label or instruction shown with the control.
2. **`payload.options`**: Each entry is `{ label: string, value: string }`.
   1. **`label`**: Text the user sees (for example, a product name).
   2. **`value`**: Value stored or matched in logic (for example, a SKU). They can match or differ.

<Tip>
  In an Execute Code Card, you can read context from the [event object](/docs/studio/guides/advanced/event-properties).
</Tip>

### Complete the Workflow after the dropdown

After the dropdown is sent, the user will select an option. Here are some typical ways to handle this:

1. Add a [Wait for User Input](/docs/studio/concepts/cards/capture-information#wait-for-user-input) Card so the Workflow pauses until the user interacts

2. Use an [Expression Card](/docs/studio/concepts/cards/flow-logic#expression) (or similar) to evaluate their response by checking `event.payload.value`

3. Use an **Execute Code** Card to store their choice. For example:

   ```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
   workflow.varName = event.payload.value
   ```

   Remember to [create a Workflow variable](/docs/studio/concepts/variables/scopes/workflow) (for example `varName`, type **String**) and grant access in code as needed ([variables in code](/docs/studio/concepts/variables/in-code)).

Wire these cards in order in the same Node (or connected Nodes) so the bot always waits, validates, then saves before continuing.

## Customize the placeholder text (CSS)

Classes for styling dropdowns are listed under **Use custom styles** on the [appearance settings](/docs/webchat/get-started/configure-your-webchat#use-custom-styles) page.

To replace the default **Select…** style label with your own, add custom CSS under **Bot Appearance** → **Styles** in the Studio, for example:

```css theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/* Hide the original "Select..." text */
.bpMessageBlocksDropdownButtonText {
  font-size: 0;
  color: transparent;
}

.bpMessageBlocksDropdownButtonText::before {
  content: "Choose an option...";
  font-size: 0.8rem;
  color: #7e7c7c;
}
```

Adjust `content`, `font-size`, and `color` to match your brand.

<Check>
  You can rely on **Capture Information** for dropdowns when you have more than five choices, or use `createMessage` with `type: 'dropdown'` in an Execute Code Card whenever you need a dropdown with fewer options or custom `label` and `value` pairs.
</Check>


# Send reminders to conversations
Source: https://botpress.com/docs/studio/guides/how-to/send-reminders



You can have your bot send a message to all your users' active conversations at regular intervals. This is useful if you want to send reminders, notifications, or other time-sensitive messages to your users.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
</Info>

## Step 1: Setup your Personal Access Token

Since you need to use the Botpress API to send a reminder to all users, you need to set up a Personal Access Token (PAT) for authentication.

### Create the token

1. In the upper-right corner of your workspace, select your profile picture.
2. Select **Account Settings > Access Tokens > Personal access tokens** > **Generate new token.**
3. Enter a note to remember the token's purpose—like "Reminders".
4. Select **Generate Token**.
5. Copy the generated token and store it somewhere—once you leave this page, you won't be able read it again.

### Store the token in a variable

Next, [create a configuration variable](/docs/studio/concepts/variables/scopes/configuration#create-a-configuration-variable) called `PERSONAL_ACCESS_TOKEN` and store your token in it. This will let you access the token in code.

## Step 2: Add a Fixed Schedule Trigger

Add a [Fixed Schedule](/docs/studio/concepts/cards/fixed-schedule) Trigger to your bot's [Workflow](/docs/studio/concepts/workflows). This will make sure your reminder sends on a set interval.

<Frame>
  <img alt="Fixed Schedule Trigger" />

  <img alt="Fixed Schedule Trigger" />
</Frame>

You can configure the Trigger to execute at whatever interval you'd like.

## Step 3: Add an Execute Code Card

Connect an [Execute Code](/docs/studio/concepts/cards/execute-code) Card to your Trigger:

<Frame>
  <img alt="Execute code" />

  <img alt="Execute code" />
</Frame>

## Step 4: Apply the custom code

Paste the following code into the Card's configuration:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const botId = '<your-bot-id>' // Replace with your actual bot ID (found in the Studio URL)
const botpressApiUrl = 'https://api.botpress.cloud/v1/chat/conversations'
const botpressApiKey = env.PERSONAL_ACCESS_TOKEN

const response = await axios.get(botpressApiUrl, {
  headers: {
    Authorization: `Bearer ${botpressApiKey}`,
    'x-bot-id': botId
  }
})

// Optional: Log the list of conversations
console.log(response.data)

response.data.conversations.forEach((conversation) => {
  const conversationId = conversation.id
  client.createMessage({
    conversationId,
    userId: botId,
    tags: {},
    type: 'text',
    payload: {
      text: "Don't forget to drink water!", // Your reminder message
    },
  })
})
```

Be sure to replace the placeholder value for `botId` with your actual bot ID. To find your bot ID:

1. Open your bot in the Studio.
2. Get the bot ID from the URL's path. For example:
   `https://studio.botpress.cloud/THIS_IS_YOUR_BOT_ID/`

<Check>
  Once you've published the latest version of your bot, it will send reminders to all active conversations at the specified interval.
</Check>


# Track AI spend in a table
Source: https://botpress.com/docs/studio/guides/how-to/track-ai-spend-in-table



You can store data about your bot's AI spend in a table that automatically updates throughout all your bot's conversations. This includes cost from any of your bot's AI usage, including:

* [Autonomous Nodes](/docs/studio/concepts/nodes/autonomous-node)
* [AI Cards](/docs/studio/concepts/cards/ai/introduction)
* Queries to a [Knowledge Base](/docs/studio/concepts/knowledge-base/introduction)

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
</Info>

## Step 1: Create a table

1. [Create a new table](/docs/studio/concepts/tables#creating-a-table) named `SpendTable`.
2. Add two columns to the table:
   * **Cost** (set the type to **Number**)
   * **ConversationID** (set the type to **String**)

<Frame>
  <img alt="Table" />

  <img alt="Table" />
</Frame>

## Step 2: Add a Hook to track AI spend

1. [Create a new Hook](/docs/studio/concepts/hooks#add-a-hook) with the type [After Turn End](/docs/studio/concepts/hooks#after-turn-end).
2. Paste the following code into the Hook:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Convert spend from nano-dollars to dollars
const llm_spend = metadata.tokens.cost / 1000000000;

// Create a row for the current turn's AI spend
client.createTableRows({
  table: 'SpendTable',
  rows: [
    {
      Cost: llm_spend,
      ConversationID: event.conversationId,
    }
  ]
});
```

This Hook runs after each turn—that is, after the bot has received a message, processed it, and sent its response. The code snippet above does the following:

* Retrieves the AI spend for the current turn
* Convert the cost from nano-dollars into standard dollars
* Saves the cost and conversation ID to the `SpendTable`

## Step 3: Test your table

Try chatting with your bot in the emulator. After every message your bot sends, your table should automatically create a new row. The AI spend will display in the **Cost** column:

<Frame>
  <img alt="Table with AI spend" />

  <img alt="Table with AI spend" />
</Frame>

<Check>
  Your table will now keep a record of your bot's AI spend for each turn.
</Check>

## Step 4 (Optional): Calculate total AI spend per conversation

Your table now stores the AI spend for each turn—but you can also store each conversation's total AI spend in a separate table.

1. Create a second table named `TotalSpendTable`.
2. Add the same two columns as the first table:
   * **Cost** (set the type to **Number**)
   * **ConversationID** (set the type to **String**)
3. [Create a new Hook](/docs/studio/concepts/hooks#add-a-hook) with the type [After Conversation End](/docs/studio/concepts/hooks#after-conversation-end).
4. Paste the following code into the Hook:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// Finds table rows with the current conversation ID
const tableResponse = await client.findTableRows({
  table: 'SpendTable',
  filter: {
    ConversationID: event.conversationId
  }
});

// Calculates the total AI spend for the conversation
let totalSpend = 0;
for (let i = 0; i < tableResponse.rows.length; i++) {
  totalSpend += tableResponse.rows[i].Cost;
};

// Creates a row in the new table with the total AI spend for the conversation
client.createTableRows({
  table: 'TotalSpendTable',
  rows: [
    {
      Cost: totalSpend,
      ConversationID: event.conversationId,
    }
  ]
});
```

This Hook runs after the end of each conversation. The code snippet above does the following:

* Retrieves the AI spend for each turn of the conversation
* Sums them up to get the total AI spend for the conversation
* Creates a row in `TotalSpendTable` with the total AI spend for the conversation

<Warning>
  If you're using an Autonomous Node in your main [Workflow](/docs/studio/concepts/workflows), the conversation will only end when it [times out](/docs/studio/concepts/bot-settings#inactivity-timeout). This means you'll need to wait for the duration of your bot's inactivity timeout before your table updates with the total AI spend.
</Warning>


# Translate Webchat UI
Source: https://botpress.com/docs/studio/guides/how-to/translate



If your bot is having conversations in a language other than English, you can translate its [Webchat](/docs/webchat/) UI to match. This includes the bot's greeting, buttons, and any other text that appears in the Webchat window.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * Knowledge of CSS

  For the purposes of this guide, we'll translate the bot's Webchat UI to French. However, you can use the same steps to translate your bot's Webchat UI into any language.
</Info>

<Tip>
  Visual learner? Check out our [YouTube guide](https://www.youtube.com/watch?v=afZCpkWHZsI) on translating your bot.
</Tip>

## Step 1: Translate elements from Webchat settings

You can translate some elements of the Webchat UI directly from your bot's [Webchat settings](/docs/webchat/get-started/configure-your-webchat):

### Name and description

To translate the name and description of your bot, modify the **Bot Name** and **Description** fields:

<Frame>
  <img alt="Translate name and description" />
</Frame>

### Composer placeholder

To translate the placeholder text in the Composer, modify the **Composer placeholder** field:

<Frame>
  <img alt="Translate composer placeholder" />
</Frame>

## Step 2: Translate elements with CSS

Other elements of the Webchat UI need to be translated using CSS. To modify Webchat's built-in CSS classes:

1. Open your bot's [Webchat settings](/docs/webchat/get-started/configure-your-webchat).
2. Go to **Bot Appearance**, then scroll to the **Styles** section.
3. Copy and paste the CSS snippets below into the **Styles** section, then modify the highlighted lines as needed.

<Tip>
  For a full list of Webchat CSS classes, check out our [guide on styling Webchat](/docs/webchat/get-started/configure-your-webchat#use-custom-styles).
</Tip>

### New conversation modal

You can translate the modal that appears when a user restarts a conversation:

<Frame>
  <img alt="New conversation modal" />
</Frame>

Just copy and paste the following CSS to the **Styles** section of your bot's Webchat settings, then modify the highlighted lines as needed:

```css [expandable] {9, 24, 38} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/* Change the modal's title */
.bpModalTitle {
    visibility: hidden;
    position: relative;
}
.bpModalTitle:after {
    visibility: visible;
    position: absolute;
    content: "Créer une nouvelle conversation"; /* Replace this with your own translation*/
}

/* Change "New Conversation" */
.bpModalButtonConfirm {
  position: relative;
  color: transparent;
}
.bpModalButtonConfirm:after {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  color: var(--message-text);
  white-space: nowrap;
  content: "Nouvelle conversation"; /* Replace this with your own translation*/
}

.bpModalButtonCancel {
    visibility: hidden;
    position: relative;
}

.bpModalButtonCancel:after {
    visibility: visible;
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    content: "Annuler"; /* Replace this with your own translation*/
}
```

### "Today" label

You can translate the "Today" label that appears in a Webchat conversation:

<Frame>
  <img alt="Today label" />
</Frame>

Just copy and paste the following CSS to the **Styles** section of your bot's Webchat settings, then modify the highlighted lines as needed:

```css [expandable] {8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/* Change the "Today" label text */
div.bpMessageContainer[data-direction="system"] > p.bpMessageBlocksTextText {
  visibility: hidden !important;
  position: relative !important;
}

div.bpMessageContainer[data-direction="system"] > p.bpMessageBlocksTextText::before {
  content: "Aujourd'hui" !important; /* Replace this with your own translation*/
  visibility: visible !important;
  position: absolute !important;
  top: 0;
  left: 0;
  white-space: nowrap;
}
```

<Check>
  Your bot's Webchat UI is now translated!
</Check>

### Delivery status

You can change the "Delivered" label that appears after a user message is received:

<Frame>
  <img alt="Delivery status" />

  <img alt="Delivery status" />
</Frame>

Just copy and paste the following CSS to the **Styles** section of your bot's Webchat settings, then modify the highlighted lines as needed:

```css highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.bpReset .bpMessageDeliveryStatus::after {
    content: "Envoyé"; /* Replace this with your own translation*/
}
```


# Introduction
Source: https://botpress.com/docs/studio/guides/introduction



We believe the best way to learn Botpress is to **start using it**. Once you've finished the [Quickstart guide](/docs/get-started/quick-start) and deployed your first bot, follow the how-to guides in this section and start building.

<Tip>
  Visual learner? You can find helpful video guides on the [Botpress YouTube channel](https://www.youtube.com/@Botpress). Whenever a page in this section has a corresponding video guide, we'll link to it.

  You can also check out the [Botpress Academy](https://botpress.com/academy) for crash courses on [pricing](https://botpress.com/academy-course/pricing), [navigating the UI](https://botpress.com/academy-course/ui-guide-studio), and more.
</Tip>

## Learn by doing

Botpress is a powerful, customizable platform—this means no one user will have exactly the same needs when building a bot.

Our how-to guides are great for learning common use-cases and troubleshooting issues. However, **they might not walk you through every step of your own process**—and that's okay! We want to help you build confidence to experiment, so you can build bots that behave exactly how you want.


# Introduction to Studio
Source: https://botpress.com/docs/studio/introduction

Development environment for building AI agents and chatbots.

[Botpress Studio](https://studio.botpress.cloud) is an **integrated development environment (IDE)** for building, testing, and managing AI agents and chatbots. It combines advanced development tools with the simplicity of a **visual, drag-and-drop interface**, making it the central platform for all your bot development needs.

<Tip>
  This section contains reference material for all concepts related to Botpress Studio. If you're looking for how-to guides, check out the [Guides section](/docs/studio/guides/introduction).
</Tip>

## Key concepts

<CardGroup>
  <Card title="Workflows" icon="workflow" href="/studio/concepts/workflows">
    Sequences of steps your bot takes
  </Card>

  <Card title="Nodes" icon="square-mouse-pointer" href="/studio/concepts/nodes">
    Steps in a Workflow
  </Card>

  <Card title="Cards" icon="rows-3" href="/studio/concepts/cards">
    Actions your bot can take within a Node
  </Card>

  <Card title="Knowledge Bases" icon="book-open" href="/studio/concepts/knowledge-base">
    Sources your bot can refer to
  </Card>

  <Card title="Tables" icon="table" href="/studio/concepts/tables">
    Local databases for storing information
  </Card>

  <Card title="Variables" icon="variable" href="/studio/concepts/variables">
    Containers for storing and reusing data
  </Card>
</CardGroup>


# Adding Cards
Source: https://botpress.com/docs/tutorial/basics/custom-logic/adding-cards



An empty Node isn't very interesting. To make it do something, we can add a *Card*—an individual task your bot performs within a Node.

Since customers tend to ask about opening hours, let's add a Card that displays them as soon as the conversation starts:

1. In the new Node, select **+ Add Card**.
2. Under **Send Messages**, select **Text**.

<Frame>
  <img alt="Card" />

  <img alt="Card" />
</Frame>

Notice that adding a Card opens the **Inspector** on the right side of the Studio:

<Frame>
  <img alt="Card inspector" />

  <img alt="Card inspector" />
</Frame>

Let's add our greeting. In the **Message to send** field, paste the following:

```txt wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Hello! I'm Teddy, 🐶 the customer support bot for Teddy's Pet Shop. Our opening hours are:

Monday-Friday: 10:00 AM to 6:00 PM
Saturday-Sunday: 11:00 AM to 3:00 PM
```

Now we can test it out. Switch back to the **Emulator** and select **Test your bot**:

<Frame>
  <img alt="Custom greeting test" />

  <img alt="Custom greeting test" />
</Frame>

Nice! The bot now displays a custom greeting with the opening hours.


# Creating Nodes
Source: https://botpress.com/docs/tutorial/basics/custom-logic/creating-nodes



Let's create a new Node and add a step to our bot's logic:

1. Select and hold the right edge of the Start Node.
2. Drag outwards to create a new transition.
3. Release anywhere on the canvas. You'll see a list of Node types to choose from—select **Standard Node**.

You just created a new Node! Notice that because you dragged out from the edge of the Start Node, it automatically transitioned to the new Node:

<Frame>
  <img alt="New Standard Node" />

  <img alt="New Standard Node" />
</Frame>

Standard Nodes, unlike Autonomous Nodes, don't use AI by default. This makes them great for hard-coding behaviour into your bot.

<GoodToKnow>
  You can drag-and-drop Nodes anywhere in your Workflow. This doesn’t affect your bot’s behavior—it just helps keep your Workflow organized.
</GoodToKnow>


# Using custom logic with AI
Source: https://botpress.com/docs/tutorial/basics/custom-logic/using-custom-logic-with-ai



Having a custom greeting is great, but we still want the bot to respond with AI after displaying it. Let's connect the Standard Node to the Autonomous Node:

<Frame>
  <img alt="Connected Nodes" />

  <img alt="Connected Nodes" />
</Frame>

Now, when you test in the Emulator, your bot begins the conversation with your hard-coded message. Then, the Autonomous Node takes the wheel for any further responses:

<Frame>
  <img alt="Custom logic with AI" />

  <img alt="Custom logic with AI" />
</Frame>

You can use any combination of Standard Nodes and Autonomous Nodes to customize your bot's behaviour.

<GoodToKnow>
  **Why can't I transition from an Autonomous Node?**

  You may have noticed that the Autonomous Node doesn't have a right edge, meaning you can't transition from an Autonomous Node to another Node.

  This is intentional—since the Autonomous Node uses AI to generate responses in a loop, it needs a different approach for transitioning out of that loop. We'll cover this in a later section, so don't worry about it for now.
</GoodToKnow>


# Workflows
Source: https://botpress.com/docs/tutorial/basics/custom-logic/workflows



So far, we've only had our bot generate responses using AI. In practice, though, you might run into situations where you want your bot to perform some hard-coded logic.

In Studio, you can do this using *Workflows*. A Workflow is a drag-and-drop canvas that represents the steps your bot follows during a conversation with a user.

## Nodes

Each step in a Workflow is represented by a *Node*. Let's open the Main Workflow and take a look at its Nodes:

1. Go to the **<Icon icon="workflow" /> Workflows** section in the left sidebar.
2. Select your **Main** Workflow. It should look something like this:

<Frame>
  <img alt="Main Workflow" />

  <img alt="Main Workflow" />
</Frame>

The Main Workflow contains the main logic for your bot—it executes as soon as a user starts a new conversation. By default, it contains:

* A *Start Node*, which starts the conversation
* An *Autonomous Node*, which generates AI responses
* An *End Node*, which ends the conversation

<GoodToKnow>
  You may have noticed the Autonomous Node has an **Instructions** field with the same instructions we provided earlier. This is no coincidence! The settings on Studio's home screen are shortcuts to configure the Autonomous Node.
</GoodToKnow>

## Transitions

Notice the path connecting the Start Node and the Autonomous Node:

<Frame>
  <img alt="Transition" />

  <img alt="Transition" />
</Frame>

This is a *transition*. It tells your bot:

> "When the conversation starts, go directly to the Autonomous Node."


# Adding knowledge
Source: https://botpress.com/docs/tutorial/basics/first-steps/adding-knowledge



Now that our bot has a custom prompt, let's try asking it a question:

<Frame>
  <img alt="Question" />

  <img alt="Question" />
</Frame>

That's not very helpful. The bot couldn't answer the question because we haven't given it the store's opening hours. Let's add them:

1. Under **<Icon icon="book-open" /> Knowledge Bases**, select **Rich Text**.
2. Select the newly created rich text file.

This opens a blank text field. Copy and paste in the following text:

```txt wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Monday-Friday: 10:00 AM to 6:00 PM
Saturday-Sunday: 11:00 AM to 3:00 PM
```

Now, let's try that same question again in the emulator:

<Frame>
  <img alt="Question with Knowledge Base" />

  <img alt="Question with Knowledge Base" />
</Frame>

Much better! The bot was able to answer the question correctly.


# Prompting
Source: https://botpress.com/docs/tutorial/basics/first-steps/prompting



In Botpress, an AI agent is a bot that follows a *prompt* (instructions) to respond to users.

You can view your bot's prompt in Studio. After skipping the initial setup, select **Edit in Studio**. This opens Studio in a new tab—you'll see the prompt under **<Icon icon="list-checks" /> Instructions** at the top of the page. It should look something like this:

<Frame>
  <img alt="Instructions" />

  <img alt="Instructions" />
</Frame>

## Write a custom prompt

This isn't a very useful prompt by itself, so let's write a better one. Erase everything in the **Instructions** section, then copy and paste in the following prompt:

```txt wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
You are Teddy 🐶, the customer support bot for Teddy's Pet Shop. Introduce yourself and help customers with any questions.
```

We can test this new prompt using the Emulator on the right side of the Studio. To start a conversation, just select **Test your bot**, or type a message into the text field:

<Frame>
  <img alt="Test prompt" />

  <img alt="Test prompt" />
</Frame>

Nice! The bot followed our instructions.


# Assigning a value
Source: https://botpress.com/docs/tutorial/basics/storing-information/assigning-a-value



A newly-created variable is like an empty box—you need put something inside it before you can use it. This is called *assigning a value* to your variable.

Let's use our `firstName` variable to remember the user's first name. Go back to the Main Workflow and select your Autonomous Node. This opens its inspector:

<Frame>
  <img alt="Autonomous Node inspector" />

  <img alt="Autonomous Node inspector" />
</Frame>

## Giving access to variables

By default, the Autonomous Node can't check what's in a variable or assign it a different value.

Let's give it access. Select **+ Add variable(s)**, then select `workflow.firstName`. Then, check **Allow write access**, so your bot has permission to modify the variable.

<Frame>
  <img alt="Variable access" />

  <img alt="Variable access" />
</Frame>

## Modifying your prompt

Next, modify the prompt so your bot knows how to work with the variable. Erase everything in the **Instructions** field, then paste the following:

```txt wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
You are Teddy 🐶, the customer support bot for Teddy's Pet Shop.

If the `firstName` variable has a value, use it to address the user by name. If not, prompt the user to enter their name, then assign it to `firstName`.
```

Now, switch back to the Emulator and start a conversation with your bot:

<Frame>
  <img alt="Variable test" />

  <img alt="Variable test" />
</Frame>

Nice! Our modified prompt worked. If you look back at the Variables section, you can see that the value updated:

<Frame>
  <img alt="New value" />

  <img alt="New value" />
</Frame>


# Scoping variables
Source: https://botpress.com/docs/tutorial/basics/storing-information/scoping-variables



Every variable has a *scope* that determines where and when your bot can access it.

Try restarting the conversation. Select **<Icon icon="rotate-ccw" />** in the Emulator, then send a message:

<Frame>
  <img alt="New conversation" />

  <img alt="New conversation" />
</Frame>

That's not ideal—the bot asked for our name again, even though we already told it in a previous conversation.

This is because `firstName` is a *Workflow* variable—it keeps the same value for the current Workflow, then resets when the Workflow is done its execution. Since each new conversation re-executes the Main Workflow, the value resets every time.

<GoodToKnow>
  Newly-created variables have the Workflow scope by default.
</GoodToKnow>

## Changing a variable's scope

Let's change `firstName` to a *User* variable:

1. In the Variables section, hover over `firstName` and select **<Icon icon="pen" />** to edit it.
2. In the **Scope** drop-down, switch from **Workflow** to **User**.
3. Select **Save**.

Now, go back to the Emulator and repeat the process. Start one conversation and tell it your name:

<Frame>
  <img alt="Variable test" />

  <img alt="Variable test" />
</Frame>

Then, select **<Icon icon="rotate-ccw" />** to restart the conversation and send a message:

<Frame>
  <img alt="User variable test" />

  <img alt="User variable test" />
</Frame>

Much better! The bot remembered the name from our previous conversation. Notice that in the Variables section, the value stayed the same:

<Frame>
  <img alt="User variable" />

  <img alt="User variable" />
</Frame>


# Variables
Source: https://botpress.com/docs/tutorial/basics/storing-information/variables



Sometimes, it's useful for your bot to remember some information—for example, about a specific user or conversation.

You can do this using *variables*. A variable is a container that lets you store information from somewhere in Botpress Studio and reuse it somewhere else.

Create a new variable in the bottom-left section of the Studio:

<Frame>
  <img alt="Variable section" />

  <img alt="Variable section" />
</Frame>

1. Select **<Icon icon="plus" />** in the upper-right corner.
2. In the name field, enter `firstName`.
3. Select **Add** to save your variable:

<Frame>
  <img alt="Variable" />

  <img alt="Variable" />
</Frame>


# Introduction
Source: https://botpress.com/docs/tutorial/introduction



Welcome to the Botpress tutorial! This will teach you the basics of building, testing, and deploying AI agents using Botpress Studio.

## What is Botpress?

Botpress is an all-in-one platform for building AI agents powered by the latest LLMs.

Unlike other platforms for building AI agents, *Botpress handles every step of the bot development process*, from building to deployment. You don't need to host anything yourself or worry about managing infrastructure—everything runs securely and seamlessly in the cloud.

## Who is this tutorial for?

If you pressed **Skip** during the [Quickstart guide](/docs/get-started/quick-start), this tutorial is for you.

When you first log in to Botpress, we offer to quickly spin up an AI agent using information about your business. However, we understand that some bot builders want to get creative right away. If that's you, keep reading!

## How should I use this tutorial?

We recommend going from start to finish.

Each section presents an exercise that teaches you about a feature. **Later exercises build on the knowledge gained in earlier ones**, so following them in order ensures that you never miss anything.

These exercises won't teach you everything there is to know about every single feature—that's not helpful for learning. Instead, you'll learn what's necessary to accomplish the current exercise.

<GoodToKnow>
  Any optional (but good to know) information will go in a callout like this one.

  If you get curious about a feature after finishing an exercise, you can check out our documentation on [Studio concepts](/docs/studio/introduction) to keep reading.
</GoodToKnow>

## Do I need to know how to code?

No.

In Botpress, you can use as little or as much code as you need, *including no code at all*. While code can help you customize your bot's behaviour in powerful ways, it's entirely possible to build a powerful AI agent without it.

<Note>
  Later in the tutorial, you may encounter features that are necessarily code-based. In this case, we'll let you know at the top of the page.
</Note>

## Start the tutorial

Ready? Hit **Next** below to start the tutorial!


# Configure Webchat
Source: https://botpress.com/docs/webchat/get-started/configure-your-webchat



<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start/)
  * Familiarity with CSS (if you want to use custom styles)
</Info>

You can configure your bot in the Dashboard:

1. Open your Botpress workspace.
2. Select the bot you want to configure, then go to **<Icon icon="settings-2" /> Webchat**.

Here's a breakdown of each configuration section:

## Bot identity

This section lets you configure general information about your bot:

* Your bot's avatar (defaults to the first letter of your bot's name)
* Your bot's display name (defaults to `Bot`)
* Your bot's description (optional)
* A placeholder for your bot's composer (defaults to `Type your message...`)
* A custom footer for your bot (requires a [Plus plan](https://botpress.com/pricing))
* A custom avatar for the Floating Action Button (FAB)

### Contact

You can also configure optional contact information for your bot:

* Email address
* Phone number
* Website
* Terms of service
* Privacy policy

## Bot appearance

This section contains styling options for Webchat:

* Primary colour (defaults to `#3276EA`). Choose a recommended colour, or use the colour picker to specify a hex code.
* Font (defaults to **Inter**). Use the search bar to choose any available Google Font.
* Theme mode (defaults to **Light**)
* Header style (defaults to **Glass**)
* Message styling (defaults to **Solid**)
* Corner radius (defaults to fully rounded)

You can view your changes in the Webchat preview on the right side of the screen. Whenever you want to update the bot's configuration, select **Publish Configuration** in the upper-right corner.

<Warning>
  Styles from this section won't apply if you're using the [Webchat React library](/docs/webchat/react-library/get-started). In this case, use the [configuration prop](/docs/webchat/react-library/components/webchat#param-configuration) to configure Webchat.
</Warning>

### Use custom styles

If you want to customize your bot's appearance further, you can modify the built-in CSS classes in the **Styles** section. Here's a list of all CSS classes available:

<Accordion title="CSS Classes">
  | CSS Class                                          | Element description                                             |
  | :------------------------------------------------- | :-------------------------------------------------------------- |
  | `bpContainer`                                      | Main Webchat container                                          |
  | `bpDropzoneOverlay`                                | Overlay shown when dragging files into the chat                 |
  | `bpLoader`                                         | Loader/spinner container for loading states                     |
  | `bpModalOverlay`                                   | Background overlay behind modals                                |
  | `bpModalContainer`                                 | Wrapper for the modal dialog                                    |
  | `bpModalTitle`                                     | Styles the title text in modals                                 |
  | `bpModalDescription`                               | Styles the description text in modals                           |
  | `bpModalContentContainer`                          | Container for content inside the modal                          |
  | `bpModalContentTextArea`                           | Text area element inside modals                                 |
  | `bpModalButtonContainer`                           | Wrapper for modal action buttons                                |
  | `bpModalButtonConfirm`                             | Styles the confirm button in modals                             |
  | `bpModalButtonCancel`                              | Styles the cancel button in modals                              |
  | `bpMessagePreviewContainer`                        | Container for message preview popups                            |
  | `bpMessagePreviewMessage`                          | Message text in preview popups                                  |
  | `bpMessagePreviewDescription`                      | Description text in preview popups                              |
  | `bpMessagePreviewCloseButton`                      | Close button for message preview                                |
  | `bpMessagePreviewAvatarContainer`                  | Container for avatar in message preview                         |
  | `bpMessagePreviewAvatarImage`                      | Avatar image in message preview                                 |
  | `bpMessagePreviewAvatarFallback`                   | Fallback avatar styling in message preview                      |
  | `bpFabContainer`                                   | Container for the floating action button                        |
  | `bpFabIcon`                                        | Icon inside the FAB                                             |
  | `bpFabImage`                                       | Image inside the FAB (when using custom images)                 |
  | `bpNotificationContainer`                          | Wrapper for notification messages                               |
  | `bpNotificationTitle`                              | Title text in notifications                                     |
  | `bpNotificationDescription`                        | Description text in notifications                               |
  | `bpNotificationIcon`                               | Icon displayed in notifications                                 |
  | `bpNotificationCloseIcon`                          | Close icon/button on notifications                              |
  | `bpHeaderContainer`                                | Container for the chat header                                   |
  | `bpHeaderContentContainer`                         | Wrapper for header content (title, avatar, actions)             |
  | `bpHeaderContentTitle`                             | Title text in the header                                        |
  | `bpHeaderContentDescription`                       | Description text in the header                                  |
  | `bpHeaderContentAvatarContainer`                   | Container for the header avatar                                 |
  | `bpHeaderContentAvatarImage`                       | Styles the avatar image in the header                           |
  | `bpHeaderContentAvatarFallback`                    | Fallback avatar styling if image fails                          |
  | `bpHeaderSoundToggleButton`                        | Button to toggle sound notifications in header                  |
  | `bpHeaderContentActionsContainer`                  | Wrapper for header action icons                                 |
  | `bpHeaderContentActionsIcons`                      | Styles the action icons in the header                           |
  | `bpHeaderExpandedContentContainer`                 | Container for expanded header content                           |
  | `bpHeaderExpandedContentDescriptionItemsContainer` | Wrapper for description items in expanded header                |
  | `bpHeaderExpandedContentDescriptionItemsIcon`      | Icon for each expanded header description item                  |
  | `bpHeaderExpandedContentDescriptionItemsText`      | Text for expanded header description items                      |
  | `bpHeaderExpandedContentDescriptionItemsLink`      | Link styling for expanded header description items              |
  | `bpHeaderExpandedContentGroup`                     | Grouping container for expanded header items                    |
  | `bpHeaderNewConversationIcon`                      | Icon for starting a new conversation in the header              |
  | `bpComposerWrapper`                                | Wrapper around the entire composer area                         |
  | `bpComposerContainer`                              | Container for the composer                                      |
  | `bpComposerFooter`                                 | Footer area of the composer (for example: upload/voice buttons) |
  | `bpComposerInputContainer`                         | Container for the text input field                              |
  | `bpComposerInput`                                  | Text input field styling                                        |
  | `bpComposerInputLoader`                            | Loader shown while input is processing                          |
  | `bpComposerSendButton`                             | Send button styling in the composer                             |
  | `bpComposerUploadButton`                           | File upload button in the composer                              |
  | `bpComposerVoiceButton`                            | Voice recording button in the composer                          |
  | `bpComposerFileContainer`                          | Container for attached files in the composer                    |
  | `bpComposerFileAttachement`                        | Wrapper for each file attachment                                |
  | `bpComposerFileLoader`                             | Loader shown during file upload in composer                     |
  | `bpComposerFileIconWrapper`                        | Container for the file type icon                                |
  | `bpComposerFileIcon`                               | Icon representing the file type                                 |
  | `bpComposerFileMetadata`                           | Container for file metadata (name and type)                     |
  | `bpComposerFileName`                               | Styles the file name text                                       |
  | `bpComposerFileExtension`                          | Styles the file extension/type text                             |
  | `bpComposerFileRemoveIcon`                         | Icon/button to remove an attached file                          |
  | `bpComposerFileErrorIcon`                          | Icon indicating an error with the attached file                 |
  | `bpComposerFilePreviewImage`                       | Thumbnail preview image for attachments                         |
  | `bpMessageListScrollDownButton`                    | Button to scroll to the latest message                          |
  | `bpMessageListContainer`                           | Container for the message list                                  |
  | `bpMessageListViewport`                            | Viewport area for scrolling messages                            |
  | `bpMessageListMarqueeContainer`                    | Container for marquee/announcement banners                      |
  | `bpMessageListMarqueeContent`                      | Content area for marquee messages                               |
  | `bpMessageListMarqueeTitle`                        | Title text in marquee banners                                   |
  | `bpMessageListMarqueeDescription`                  | Description text in marquee banners                             |
  | `bpMessageListMarqueeAvatarContainer`              | Container for avatars in marquee banners                        |
  | `bpMessageListMarqueeAvatarImage`                  | Avatar image in marquee banners                                 |
  | `bpMessageListMarqueeAvatarFallback`               | Fallback avatar styling in marquee banners                      |
  | `bpMessageListHeaderMessage`                       | Header message block styling                                    |
  | `bpMessageContainer`                               | Container for individual messages                               |
  | `bpMessageAvatarContainer`                         | Container for the message avatar                                |
  | `bpMessageAvatarImage`                             | Styles the avatar image in messages                             |
  | `bpMessageAvatarFallback`                          | Fallback styling for missing message avatars                    |
  | `bpMessageDeliveryStatus`                          | Delivery status indicator for messages                          |
  | `bpMessageBlocksTextHeading1`                      | H1 text block within messages                                   |
  | `bpMessageBlocksTextHeading2`                      | H2 text block within messages                                   |
  | `bpMessageBlocksTextHeading3`                      | H3 text block within messages                                   |
  | `bpMessageBlocksTextHeading4`                      | H4 text block within messages                                   |
  | `bpMessageBlocksTextUnorderedList`                 | Unordered list text block                                       |
  | `bpMessageBlocksTextOrderedList`                   | Ordered list text block                                         |
  | `bpMessageBlocksTextListItem`                      | List item text block                                            |
  | `bpMessageBlocksTextLink`                          | Hyperlink text block                                            |
  | `bpMessageBlocksTextItalic`                        | Italic text styling                                             |
  | `bpMessageBlocksTextBold`                          | Bold text styling                                               |
  | `bpMessageBlocksTextText`                          | Standard paragraph text block                                   |
  | `bpMessageBlocksTextImage`                         | Inline image block within text                                  |
  | `bpMessageBlocksTextImageError`                    | Error state for failed inline images                            |
  | `bpMessageBlocksTextHorizontalRule`                | Horizontal rule within text                                     |
  | `bpMessageBlocksTextLineBreak`                     | Line break within text                                          |
  | `bpMessageBlocksTextInput`                         | Input field block within messages                               |
  | `bpMessageBlocksTextCodeBlockContainer`            | Container for code block elements                               |
  | `bpMessageBlocksTextCodeBlockTitle`                | Title area for code blocks                                      |
  | `bpMessageBlocksTextCodeBlockCopyIcon`             | Copy-to-clipboard icon in code blocks                           |
  | `bpMessageBlocksTextCodeBlock`                     | Code block styling                                              |
  | `bpMessageBlocksTextCode`                          | Inline code text styling                                        |
  | `bpMessageBlocksTextTableContainer`                | Container for tables within messages                            |
  | `bpMessageBlocksTextTable`                         | Table element styling                                           |
  | `bpMessageBlocksTextTableHeader`                   | Table header cell styling                                       |
  | `bpMessageBlocksTextTableData`                     | Table data cell styling                                         |
  | `bpMessageBlocksTextTableRow`                      | Table row styling                                               |
  | `bpMessageBlocksAudio`                             | Audio player block styling                                      |
  | `bpMessageBlocksImageImage`                        | Image block styling                                             |
  | `bpMessageBlocksImagePlaceholder`                  | Placeholder for loading images                                  |
  | `bpSkeleton`                                       | Skeleton loader for images                                      |
  | `bpMessageBlocksVideo`                             | Video player block styling                                      |
  | `bpMessageBlocksLocationContainer`                 | Container for location blocks                                   |
  | `bpMessageBlocksLocationTitle`                     | Title text for location blocks                                  |
  | `bpMessageBlocksLocationIcon`                      | Icon for location blocks                                        |
  | `bpMessageBlocksFileContainer`                     | Container for file blocks                                       |
  | `bpMessageBlocksFileTitle`                         | Title text for file blocks                                      |
  | `bpMessageBlocksFileIcon`                          | Icon for file blocks                                            |
  | `bpMessageBlocksRow`                               | Row layout block within messages                                |
  | `bpMessageBlocksColumn`                            | Column layout block within messages                             |
  | `bpMessageBlocksBubble`                            | Chat bubble container                                           |
  | `bpMessageBlocksBubbleFeedbackContainer`           | Container for bubble feedback icons                             |
  | `bpMessageBlocksBubbleFeedbackIcon`                | Feedback icon inside bubbles                                    |
  | `bpMessageBlocksCarouselContainer`                 | Container for carousel blocks                                   |
  | `bpMessageBlocksCarouselSlidesContainer`           | Slides container within carousels                               |
  | `bpMessageBlocksCarouselBackButton`                | Back button in carousel blocks                                  |
  | `bpMessageBlocksCarouselNextButton`                | Next button in carousel blocks                                  |
  | `bpMessageBlocksDropdownButtonContainer`           | Dropdown button container                                       |
  | `bpMessageBlocksDropdownButtonText`                | Text inside dropdown buttons                                    |
  | `bpMessageBlocksDropdownButtonIcon`                | Icon inside dropdown buttons                                    |
  | `bpMessageBlocksDropdownContentContainer`          | Container for dropdown content                                  |
  | `bpMessageBlocksDropdownContentItem`               | Individual dropdown item styling                                |
  | `bpMessageBlocksButton`                            | Button block styling within messages                            |
  | `bpErrorContainer`                                 | Container for error messages                                    |
  | `bpErrorId`                                        | Error ID text styling                                           |
  | `bpErrorHeader`                                    | Header area for error display                                   |
  | `bpErrorHeaderActions`                             | Action buttons in error header                                  |
  | `bpErrorContent`                                   | Content area for error messages                                 |
  | `bpErrorTitle`                                     | Title text for error messages                                   |
  | `bpErrorMessage`                                   | Error message text styling                                      |
  | `bpErrorIcon`                                      | Icon displayed in error messages                                |
  | `bpTypingIndicatorContainer`                       | Container for typing indicator                                  |
  | `bpTypingIndicatorLoader`                          | Loader animation for typing indicator                           |
  | `bpProactiveBubbleContainer`                       | Container for proactive message bubble                          |
  | `bpProactiveBubbleContent`                         | Content area of proactive bubble                                |
  | `bpProactiveBubbleLayout`                          | Layout wrapper for proactive bubble                             |
  | `bpProactiveBubbleIcon`                            | Icon in proactive bubble                                        |
  | `bpProactiveBubbleMessage`                         | Message text in proactive bubble                                |
  | `bpProactiveBubbleCloseButton`                     | Close button for proactive bubble                               |
  | `bpProactiveBubbleArrow`                           | Arrow/pointer for proactive bubble                              |
</Accordion>

### Position Webchat on the left

By default, the Webchat FAB and the chat window appear on the right side of the screen. You can move them to the left by overriding the default CSS.

Add the following CSS to your website's stylesheet:

```css theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
.bpFabWrapper {
  left: 20px !important;
  right: auto !important;
}

.bpWebchat {
  left: 20px !important;
  right: auto !important;
}
```

This will position both the FAB icon and the main Webchat window 20 pixels from the left edge of the viewport. You can adjust the `20px` value as needed.

## Deploy settings

This section lets you configure your bot's deployment settings:

* **Chat interface**: Choose whether you want to use a toggle for the chat's visibility or [embed it in a specific element](/docs/webchat/get-started/embedding-webchat)
* **Where to show chat**: Enter the HTML ID of the container where the chat should appear (if **Chat interface** is set to **Embedded**)
* **Chat launcher**: Choose how you want to toggle Webchat (using the default chat bubble or a custom element). Available if **Chat interface** is set to **Toggle**
* **Button image**: Choose a custom image for the chat bubble (if **Chat launcher** is set to **Chat bubble**)
* **Element selector**: Enter the HTML ID of the button or element that launches the chat (if **Chat launcher** is set to **Custom element**).

### Proactive message bubble

This section lets you configure and preview a [proactive message bubble](/docs/webchat/interact/proactive-message-bubble) for Webchat. You can:

* Set a proactive message
* Set a trigger type
* Set a delay time

## Features

This section lets you configure optional features for your bot:

* **Message feedback**: Enable/disable message feedback. When enabled, you can view feedback data in the [Analytics](/docs/get-started/manage-your-agent/monitor#analytics) menu
* **Allow file upload**: Enable/disable user file upload
* **Message notification sound**: Enable sound notifications for new messages. This requires Webchat v3.3+
* **Conversation history**: Allow users to view and continue previous conversations. This requires Webchat v3.6+
* **Chat history reset**: Choose whether users can continue conversations after the tab closes (local storage) or not (local storage)

<Note>
  **Session storage vs. Local storage**

  Session storage creates a new user and conversation each time the page is re-opened. Local storage keeps them for your next visits.

  You can [learn more about local and session storage here](https://www.geeksforgeeks.org/javascript/difference-between-local-storage-session-storage-and-cookies/).
</Note>

### Advanced settings

You can also access the following advanced settings:

#### Client ID

The client ID is used to identify your bot's Webchat instance. You can use it when building with our [Webchat React library](/docs/webchat/react-library/get-started).

#### Allowed origins&#x20;

The **Allowed Origins** setting lets you manage which domains are allowed to access Webchat.

By default, this is set to **All Origins**. To restrict the allowed origins:

<Steps>
  <Step>Select **Whitelist**.</Step>
  <Step>Select **+ Add Origin**.</Step>
  <Step>Type the domain you want to allow, then select **Publish Changes**.</Step>
</Steps>


# Embed Webchat in an element
Source: https://botpress.com/docs/webchat/get-started/embed-in-element



You can embed Webchat inside a specific HTML element on your website. This hides the chat bubble that usually toggles Webchat and gives you more control over Webchat's appearance and location.

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start) using Webchat v3.3
  * Basic familiarity with HTML
</Info>

<Steps>
  <Step title="Get your Webchat element ID">
    First, get your Webchat element ID:

    1. Select your bot from your workspace.
    2. Go to **Webchat > Deploy Settings**.
    3. Under **Chat interface**, select **Embedded**.
    4. Copy the contents of the **Element ID** field.
       <Tip>
         You can also set a custom element ID in the field.
       </Tip>
    5. Scroll to the bottom of the page, then select **Save configuration**.
  </Step>

  <Step title="Add the element to your website">
    Next, add an element to your website's HTML. Set the `id` attribute to the ID you copied earlier:

    ```html theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    <div id="bp-embedded-webchat"></div>
    ```
  </Step>
</Steps>

<Check>
  Done! The Webchat window will now be visible in the element.
</Check>


# Introduction to Webchat
Source: https://botpress.com/docs/webchat/get-started/introduction

Integrate your bot into your website.

Webchat is a **custom frontend for your bot**, built by Botpress.

You can use Webchat to add your bot to your website in a variety of ways, from a simple [embed code](/docs/webchat/get-started/quick-start) to a fully customizable [React library](/docs/webchat/react-library).

<Tip>
  Looking for a way to integrate your bot in your service? Check out the [Chat API](/docs/api-reference/chat-api/introduction).
</Tip>

## Getting Started

<CardGroup>
  <Card title="Add a bot to your website" href="/webchat/get-started/quick-start" icon="message-square">
    Use a script tag to embed a bot in your website
  </Card>

  <Card title="React Library" href="/webchat/react-library" icon="react">
    Use the React library to build a Webchat component directly into your application
  </Card>
</CardGroup>

## Add your bot to your CMS

<CardGroup>
  <Card title="WordPress" href="/webchat/integrations/wordpress" icon="wordpress">
    Add a bot to your WordPress website using Webchat
  </Card>

  <Card title="Wix" href="/webchat/integrations/wix" icon="wix">
    Add a bot to your Wix website using Webchat
  </Card>

  <Card title="Webflow" href="/webchat/integrations/webflow" icon="webflow">
    Add a bot to your Webflow website using Webchat
  </Card>
</CardGroup>


# Quickstart
Source: https://botpress.com/docs/webchat/get-started/quick-start

Use the Webchat embed code to add a bot to your website.

Webchat makes it easy to embed a bot on your website. If you self-host your website, just follow the instructions on this page.

<Note>
  If you use a website-building tool like [WordPress](/docs/webchat/integrations/wordpress), [Wix](/docs/webchat/integrations/wix) or [Webflow](/docs/webchat/integrations/webflow), see the other pages in this section for instructions on how to add your bot.
</Note>

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * Basic familiarity with HTML
</Info>

<Steps>
  <Step title="Get your embed code">
    To embed a bot on your website, you need the bot's Webchat embed code. You can get the embed code from the Dashboard:

    1. Open your bot's Workspace and select the bot you want to embed.
    2. In the left sidebar, go to **Webchat** > **Deploy Settings**.
    3. Copy the **Embed code**:

    <Frame>
      <img alt="Embed code from Dashboard" />

      <img alt="Embed code from Dashboard" />
    </Frame>
  </Step>

  <Step title="Add to your website">
    Next, add the Webchat embed code to the `head` section of your website's HTML. For example:

    ```html index.html {4-5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    <!DOCTYPE html>
    <html>
    <head>
      <script src="https://cdn.botpress.cloud/webchat/vX.X/inject.js"></script>
      <script src="https://files.bpcontent.cloud/xxxx/xx/xx/xx/xxxxxxxxxxxxx-xxxxxxxx.js" defer></script>
    </head>
    <body>
      <!-- Website content -->
    </body>
    </html>
    ```
  </Step>

  <Step>
    You're all set! Open your website and start chatting with your bot. It should look something like this:

    <Frame>
      <img alt="Webchat" />

      <img alt="Webchat" />
    </Frame>
  </Step>
</Steps>

<Check>
  Done! Your bot is now live on your website.
</Check>

## Next steps

Now that you've added your bot, try [styling it](./configure-your-webchat) to match the rest of your website's user interface.


# React Native
Source: https://botpress.com/docs/webchat/integrations/react-native

Add your bot in any React Native or Expo app using react-native-webview.

<Note>
  **Why a WebView?** Botpress Cloud Webchat is a **browser** client (`window.botpress`). React Native does not run that API natively, so the supported pattern is to run the official Webchat **inside a WebView** and communicate with `postMessage` and `injectJavaScript`.

  The [`@botpress/webchat`](/docs/webchat/react-library/get-started) package targets web React. For native apps, use the WebView approach below.
</Note>

## Prerequisites

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A React Native or Expo project
  * [`react-native-webview`](https://github.com/react-native-webview/react-native-webview)
</Info>

## 1. Copy your Webchat embed code from the dashboard

Before you write any app code, grab the same embed snippet you would use on a website. In the Botpress dashboard:

1. Open your bot's Workspace and select the bot you want to embed.
2. In the left sidebar, go to **Webchat** > **Deploy Settings**.
3. Copy the **Embed code**:

<Frame>
  <img alt="Embed code from Dashboard" />

  <img alt="Embed code from Dashboard" />
</Frame>

## 2. Lay out your project files

Create a **`src`** folder at your project root if you do not already have one. A typical layout:

<Tree>
  <Tree.Folder name="src">
    <Tree.Folder name="botpress">
      <Tree.File name="getBotpressWebchat.js" />

      <Tree.File name="BpWidget.js" />

      <Tree.File name="BpWidget.d.ts" />
    </Tree.Folder>

    <Tree.Folder name="config">
      <Tree.File name="botpressConfig.js" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

| Path                                     | Purpose                                                                                                       |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **`src/botpress/getBotpressWebchat.js`** | Builds `{ html, baseUrl }` for the WebView.                                                                   |
| **`src/botpress/BpWidget.js`**           | WebView component and event bridge (`onMessage`); blocks marketing site navigation on close.                  |
| **`src/botpress/BpWidget.d.ts`**         | *(Optional, TypeScript only)* Types for `BpWidget`.                                                           |
| **`src/config/botpressConfig.js`**       | Webchat URLs and optional `botId`. **Step 4** shows what goes inside `export const botpressConfig = { ... }`. |

You can instead keep files flat under `src/` and use relative imports. The examples below assume **`src/botpress/`** and **`src/config/`**.

**Path alias (optional, Expo / TypeScript):** In **`tsconfig.json`**, merge into `compilerOptions`:

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

Then imports like `import BpWidget from '@/botpress/BpWidget'` resolve. If you skip aliases, use relative imports only.

## 3. Install react-native-webview

From your project root:

<CodeGroup>
  ```bash Expo theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npx expo install react-native-webview
  ```

  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install react-native-webview
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add react-native-webview
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm add react-native-webview
  ```
</CodeGroup>

<Note>
  For bare React Native, follow [react-native-webview linking](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Getting-Started.md) if your setup requires it. Expo users can also see the [Expo WebView docs](https://docs.expo.dev/versions/latest/sdk/webview/).
</Note>

## 4. Save your Studio script URLs in one config file

Create **`src/config/botpressConfig.js`** and export a single **`botpressConfig`** object. Paste the script URLs from **Studio > Webchat > Embed** (the same values from your embed snippet). The HTML helper and the widget only read **`botConfig`**: you pass it in, and you do not duplicate URLs inside `getBotpressWebchat.js` or `BpWidget.js`.

<Note>
  **Sensitive values:** `botId` and embed URLs identify your bot. For a public repository, do not commit real values, use placeholders in git or keep this file out of version control.
</Note>

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export const botpressConfig = {
  botId: "YOUR_BOT_ID",
  injectScriptUrl: "https://cdn.botpress.cloud/webchat/v3.6/inject.js",
  embedScriptUrl: "https://files.bpcontent.cloud/YOUR/PATH/YOUR-GENERATED.js",
  baseUrl: "https://cdn.botpress.cloud/",
};
```

## 5. Build the HTML page that loads Webchat

Add **`src/botpress/getBotpressWebchat.js`**. It builds a tiny HTML page (inject script, embed script, full height container) and returns **`{ html, baseUrl }`** so you can pass it straight into `<WebView source={{ baseUrl, html }} />`.

```javascript getBotpressWebchat.js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/**
 * Builds the HTML page loaded by the WebView for Botpress Cloud webchat v3.
 * @param {Record<string, unknown>} botConfig Pass `botpressConfig` from src/config/botpressConfig.js
 * @returns {{ html: string, baseUrl: string }}
 */
const getBotpressWebchat = (botConfig) => {
  // Official inject script (Botpress loader); falls back to a known default if omitted.
  const injectUrl =
    botConfig.injectScriptUrl ||
    "https://cdn.botpress.cloud/webchat/v3.6/inject.js";
  // Studio-generated bundle URL (required). This wires your bot into the page.
  const embedUrl = botConfig.embedScriptUrl;
  if (!embedUrl || typeof embedUrl !== "string") {
    throw new Error(
      "botConfig.embedScriptUrl is required (paste the second script URL from Studio embed)",
    );
  }
  // Origin passed to WebView as `baseUrl` so relative URLs in the HTML resolve correctly.
  const baseUrl = botConfig.baseUrl || "https://cdn.botpress.cloud/";

  // Minimal HTML shell: viewport, full-height container, then inject + embed scripts (matches Studio order).
  const html = `<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <style>
      html, body { margin: 0; height: 100%; }
      body {
        display: flex;
        flex-direction: column;
        height: 100vh;
      }
      #bp-web-widget-container {
        height: 100%;
        width: 100%;
        flex: 1;
      }
    </style>
    <title>Chatbot</title>
  </head>
  <body>
    <script src="${injectUrl}"></script>
    <script src="${embedUrl}" defer></script>
  </body>
</html>`;

  // WebView expects this pair: `source={{ baseUrl, html }}`.
  return { baseUrl, html };
};

module.exports = getBotpressWebchat;
```

## 6. Show Webchat in a WebView and forward events to React Native

Create **`src/botpress/BpWidget.js`**. It renders a **`WebView`** that loads your HTML, then relays what happens inside the page to your React Native layer:

* Puts the page from **`getBotpressWebchat(botConfig)`** into the **`WebView`**.
* Injects a script that subscribes to **`window.botpress`** and sends each event to React Native with **`postMessage`** (you read them in **`onMessage`** as JSON strings).
* Intercepts navigation to **`botpress.com`** or **`*.botpress.com`** when the user closes the widget and runs **`window.botpress.close()`** instead to close the webchat interface.

```javascript BpWidget.js expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/**
 * WebView wrapper for Botpress webchat v3: window.botpress API, events to React Native via postMessage.
 */
import { WebView } from "react-native-webview";
import getBotpressWebchat from "./getBotpressWebchat";
import React, { useCallback, useRef } from "react";

const broadcastToReactNative = `
(function () {
  // Sends one event payload to React Native as a JSON string (read in onMessage).
  function post(ev, data) {
    try {
      window.ReactNativeWebView.postMessage(JSON.stringify({ event: ev, data: data }));
    } catch (e) {}
  }
  // Subscribes to window.botpress once it exists and mirrors events into React Native.
  function wire() {
    if (!window.botpress || typeof window.botpress.on !== "function") return false;
    window.botpress.on("webchat:initialized", function () {
      try { window.botpress.open(); } catch (e) {}
    });
    [
      "message",
      "webchat:initialized",
      "webchat:ready",
      "webchat:opened",
      "webchat:closed",
      "customEvent",
      "error",
      "conversation",
    ].forEach(function (ev) {
      window.botpress.on(ev, function (data) {
        post(ev, data);
      });
    });
    // Fallback open in case the widget did not auto-open after init.
    setTimeout(function () {
      try { window.botpress.open(); } catch (e) {}
    }, 400);
    return true;
  }
  // Poll until botpress is ready (or give up after ~12s) so inject order does not race.
  var n = 0;
  var id = setInterval(function () {
    if (wire() || ++n > 240) clearInterval(id);
  }, 50);
})();
true;
`;

const closeChatJs = `
try {
  // Programmatic close when we block a navigation attempt (through onShouldStartLoadWithRequest).
  if (window.botpress && typeof window.botpress.close === "function") {
    window.botpress.close();
  }
} catch (e) {}
true;
`;

// Returns true when a navigation URL is the public Botpress marketing site (close button behavior).
function isBotpressMarketingSiteUrl(url) {
  if (!url || url.startsWith("about:") || url.startsWith("blob:") || url.startsWith("data:")) {
    return false;
  }
  try {
    const h = new URL(url).hostname;
    return h === "botpress.com" || h.endsWith(".botpress.com");
  } catch {
    return false;
  }
}

export default function BpWidget(props) {
  const { botConfig, onMessage } = props;
  const webref = useRef(null);

  // Build the in-memory HTML page and origin for this WebView instance.
  const { html, baseUrl } = getBotpressWebchat(botConfig);

  // Intercept navigations: block opening botpress.com inside the frame and close chat instead.
  const onShouldStartLoadWithRequest = useCallback((request) => {
    const { url } = request;
    if (isBotpressMarketingSiteUrl(url)) {
      webref.current?.injectJavaScript(closeChatJs);
      return false;
    }
    return true;
  }, []);

  // Webchat needs JavaScript and DOM storage; originWhitelist allows loading scripts from Botpress CDNs.
  return (
    <WebView
      ref={webref}
      style={{ flex: 1 }}
      source={{
        baseUrl,
        html,
      }}
      onMessage={onMessage}
      injectedJavaScript={broadcastToReactNative}
      onShouldStartLoadWithRequest={onShouldStartLoadWithRequest}
      setSupportMultipleWindows={false}
      javaScriptEnabled
      domStorageEnabled
      originWhitelist={["*"]}
    />
  );
}
```

<Note>
  **`onMessage` format:** `event.nativeEvent.data` is a **string**. Parse with `JSON.parse`. Shape: **`{ event: string, data: unknown }`**.
</Note>

## 7. Optional: add TypeScript types for the widget

If you use TypeScript, add **`src/botpress/BpWidget.d.ts`** next to **`BpWidget.js`** so imports and props are typed:

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import type { FunctionComponent } from "react";

/** Props for the WebView wrapper: Studio-derived config and optional React Native message handler. */
export interface BpWidgetProps {
  botConfig: Record<string, unknown>;
  onMessage?: (e: { nativeEvent: { data: string } }) => void;
}

/** Default export from BpWidget.js (JavaScript component with these props). */
declare const BpWidget: FunctionComponent<BpWidgetProps>;

export default BpWidget;
```

## 8. Render the Webchat widget on a screen

Import **`BpWidget`** and **`botpressConfig`**, then render it full screen or inside any `View` that uses `flex: 1`. Adjust import paths to your real paths (for example Expo Router **`app/index.tsx`**, a root **`App.js`**, or **`src/screens/…`**).

```tsx ChatScreen.tsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { StyleSheet, View } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";

import BpWidget from "@/botpress/BpWidget";
import { botpressConfig } from "@/config/botpressConfig";

/** Screen that fills the safe area with the Botpress WebView-powered widget. */
export default function ChatScreen() {
  return (
    <SafeAreaView style={styles.safeArea}>
      <View style={styles.main}>
        <BpWidget
          botConfig={botpressConfig}
          onMessage={(e) => {
            // Bridge: WebView posts JSON strings; parse to `{ event, data }` for logging or app logic.
            const raw = e.nativeEvent?.data;
            if (!raw) return;
            try {
              const msg = JSON.parse(raw);
              console.log(msg.event, msg.data);
            } catch {
              /* non-JSON */
            }
          }}
        />
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  safeArea: { flex: 1 },
  main: { flex: 1 },
});
```

## 9. Run your app

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install
npx expo start
```

<Check>
  Open the iOS Simulator, Android emulator, or a physical device from there. Your bot should load inside the WebView when you run the app.
</Check>

## Troubleshooting

| Problem                                  | What to check                                                                                                                                                                    |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Blank WebView                            | **`embedScriptUrl`** in **`botpressConfig.js`** must be the **`files.bpcontent.cloud/...`** URL from Studio.                                                                     |
| Error: `embedScriptUrl is required`      | Set `embedScriptUrl` in `botpressConfig`.                                                                                                                                        |
| Close (X) opens the Botpress.com website | Keep **`onShouldStartLoadWithRequest`** and **`closeChatJs`** in `BpWidget.js` as shown in that section.                                                                         |
| Fonts look wrong                         | Tune appearance in **Botpress Studio**; avoid forcing global `font-family` in the HTML shell.                                                                                    |
| Android keyboard covers the composer     | In **`app.json`** (Expo), under **`expo.android`**, set `"softwareKeyboardLayoutMode": "resize"`. Rebuild the native Android app after changing this (not only a Metro refresh). |

## Next steps

Now that Webchat runs in your app, try [styling](/docs/webchat/get-started/configure-your-webchat) it in Studio to match your product. For more control over the embed, see [Embed Webchat](/docs/webchat/get-started/embedding-webchat) and the [Webchat interaction reference](/docs/webchat/interact/reference).


# Webflow
Source: https://botpress.com/docs/webchat/integrations/webflow

Add a bot to your Webflow website using Webchat.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A Webflow website with a [plan that allows adding custom scripts](https://webflow.com/pricing)
</Info>

<Steps>
  <Step title="Get your embed code">
    To embed a bot on your website, you need the bot's Webchat embed code. You can get the embed code from the Dashboard:

    1. Open your bot's Workspace and select the bot you want to embed.
    2. In the left sidebar, go to **Webchat** > **Deploy Settings**.
    3. Copy the **Embed code**:

    <Frame>
      <img alt="Embed code from Dashboard" />

      <img alt="Embed code from Dashboard" />
    </Frame>
  </Step>

  <Step title="Add to your Webflow website">
    1. Login to your [Webflow](https://webflow.com/login) account and navigate to **Site Settings**.
    2. Select the **Custom code** tab.
    3. Paste the Webchat embed code in the **Head code** section.
    4. Select **Save Changes**.
  </Step>
</Steps>

<Check>
  Your bot is now live on your Webflow website.
</Check>

## Next steps

Now that you've added your bot, try [styling](/docs/webchat/get-started/configure-your-webchat) it to match the rest of your website's user interface.


# Wix
Source: https://botpress.com/docs/webchat/integrations/wix

Add a bot to your Wix website using Webchat.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A Wix website with a [plan that allows adding custom scripts](https://www.wix.com/plans)
  * A [domain connected to your Wix website](https://support.wix.com/en/article/connecting-a-domain-to-the-wix-name-servers)
  * Familiarity with HTML (if you want to embed in an HTML div)
</Info>

<Tip>
  Visual learner?

  Check out our [Wix guide](https://www.youtube.com/watch?v=rG7dguRDFIA\&t=1068s) on YouTube, which teaches you how to build and embed a bot on your Wix site.
</Tip>

## As a chat bubble

<Steps>
  <Step title="Get your embed code">
    To embed a bot on your website, you need the bot's Webchat embed code. You can get the embed code from the Dashboard:

    1. Open your bot's Workspace and select the bot you want to embed.
    2. In the left sidebar, go to **Webchat** > **Deploy Settings**.
    3. Copy the **Embed code**:

    <Frame>
      <img alt="Embed code from Dashboard" />

      <img alt="Embed code from Dashboard" />
    </Frame>
  </Step>

  <Step title="Add to your Wix website">
    Next, add the Webchat embed code to your Wix website:

    1. Login to your [Wix](https://www.wix.com) dashboard and select **Settings** in the left navigation bar.
    2. Scroll to **Advanced Settings**, then select **Custom Code**.
    3. Select **+ Add Custom Code**. Then, paste the Webchat embed code in code snippet field.
    4. Check the **All pages** option, then select **Load code once** from the drop-down menu.
    5. Check the **Body - start** option.
    6. Select **Apply**.
  </Step>
</Steps>

## In an HTML div

You can also embed your bot in an HTML div. This is useful if you want more control over where your bot appears on your Wix site.

<Steps>
  <Step title="Get your Webchat initialization script">
    <GetInitScript />
  </Step>

  <Step title="Copy the script URL">
    Open the URL in your browser and **copy the content of the page**. It should look something like this:

    ```uri https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js [expandable] theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    window.botpress.init({
        "botId": "xxxxxxxxxxxxxxxxxxxxxx",
        "configuration": {
            "website": {},
            "email": {},
            "phone": {},
            "termsOfService": {},
            "privacyPolicy": {},
            "variant": "soft",
            "themeMode": "light",
            "fontFamily": "inter"
        },
        "clientId": "xxxxxxxxxxxxxxxxxxxxxx"
    });
    ```
  </Step>

  <Step title="Add to your Wix site">
    Next, use your credentials to embed the Webchat in an HTML div on your website.

    1. Login to your [Wix](https://www.wix.com) dashboard and select **Edit Site** in the upper-right corner.
    2. Select **Add Elements** from the left sidebar.
    3. Select **Embed Code**, then select **Embed HTML**.
    4. Adjust your HTML div as you'd like.
    5. Under **Add your code here (HTTPS only)**, add the following code:

    ```html {8} [expandable] theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    <div id="webchat-container" style="position: relative; width: 100%; height: 100%;">
      <script src="https://cdn.botpress.cloud/webchat/v3.3/inject.js"></script>
      <script>
        window.botpress.on('webchat:initialized', () => {
          window.botpress.open()
        })

        // Paste your Webchat config snippet here
      </script>
      <style>
        #webchat-container {
          position: relative;
          width: 100%;
          height: 100%;
        }
        .bpFab {
          display: none;
        }
        .bpWebchat {
          position: absolute !important;
          top: 0 !important;
          left: 0 !important;
          right: 0 !important;
          bottom: 0 !important;
          width: 100% !important;
          height: 100% !important;
          max-height: 100% !important;
        }
      </style>
    </div>
    ```
  </Step>
</Steps>

## As a website

You can also embed your bot as a website via Webchat preview.

<Steps>
  <Step title="Get your shareable link">
    1. In Studio, select **Share** in the upper-right corner.
    2. Copy your bot's shareable link.
  </Step>

  <Step title="Add to your Wix website">
    1. Login to your [Wix](https://www.wix.com) dashboard and select **Edit Site** in the upper-right corner.
    2. Select **Add Elements** from the left sidebar.
    3. Select **Embed Code**, then select **Embed a site**.
    4. In the **What's the website address** field, paste your bot's link, then select **Apply.**
  </Step>
</Steps>

<Check>
  Your bot is now live on your Wix site.
</Check>

## Next steps

Now that you've added your bot, try [styling](/docs/webchat/get-started/configure-your-webchat) it to match the rest of your website's user interface.


# WordPress
Source: https://botpress.com/docs/webchat/integrations/wordpress

Add a bot to your WordPress website using Webchat.

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A WordPress website. Your website could be managed ([WordPress.org](https://wordpress.org/)) or self-hosted ([WordPress.com](https://wordpress.com/))
  * If you're self-hosting: a WordPress [plan that allows installing plugins](https://wordpress.com/pricing/)
</Info>

<Tip>
  Visual learner?

  Check out our [WordPress guide](https://www.youtube.com/watch?v=PzGFVqOzDsk) on YouTube, which teaches you how to build and embed a bot on your WordPress website.
</Tip>

<Steps>
  <Step title="Get your embed code">
    To embed a bot on your website, you need the bot's Webchat embed code. You can get the embed code from the Dashboard:

    1. Open your bot's Workspace and select the bot you want to embed.
    2. In the left sidebar, go to **Webchat** > **Deploy Settings**.
    3. Copy the **Embed code**:

    <Frame>
      <img alt="Embed code from Dashboard" />

      <img alt="Embed code from Dashboard" />
    </Frame>
  </Step>

  <Step title="Install the WPCode plugin in WordPress">
    1. Login to your [WordPress dashboard](https://login.wordpress.org).
    2. From the left navigation bar, select **Plugins**.
    3. Search for the [WPCode plugin](https://wordpress.org/plugins/insert-headers-and-footers/#description) and select **Install Now**.
  </Step>

  <Step title="Add the bot to your WordPress website">
    1. From the left navigation bar, select **Code Snippets**.
    2. Select **Add New**. Then, select **Add Your Custom Code (New Snippet)**.
    3. Select **HTML Snippet**. Then, paste your Webchat embed code into the **Code Preview** field.
    4. Scroll to the **Insertion** section, then open the **Location** drop-down menu. Select **Side Wide Body**.
    5. In the upper-right corner, set the snippet to **Active**, then select **Save Snippet**.
  </Step>
</Steps>

<Check>
  Your bot is now live on your WordPress site.
</Check>

## Next steps

Now that you've added your bot, try [styling](/docs/webchat/get-started/configure-your-webchat) it to match the rest of your website's user interface.


# Error handling
Source: https://botpress.com/docs/webchat/interact/error-handling



When Webchat encounters an error, it displays a dedicated error screen instead of the normal chat interface. Here's a breakdown of all possible error screens:

## Configuration Errors

### Missing client ID

<Frame>
  <img alt="Missing client ID" />

  <img alt="Missing client ID" />
</Frame>

* **Cause**: Client ID not provided during initialization
* **Solution**: Provide a valid client ID

### Invalid client ID

<Frame>
  <img alt="Invalid client ID" />

  <img alt="Invalid client ID" />
</Frame>

* **Cause**: Provided Client ID isn't valid
* **Solution**: Use a valid Botpress Client ID

### Missing API URL

<Frame>
  <img alt="Missing API URL" />

  <img alt="Missing API URL" />
</Frame>

* **Cause**: API URL not provided during initialization
* **Solution**: Provide a valid API URL

### Invalid API URL

<Frame>
  <img alt="Invalid API URL" />

  <img alt="Invalid API URL" />
</Frame>

* **Cause**: API URL format is incorrect
* **Solution**: Use HTTPS URL format

### Missing bot ID

<Frame>
  <img alt="Missing bot ID" />

  <img alt="Missing bot ID" />
</Frame>

* **Cause**: Bot ID not provided during initialization
* **Solution**: Provide a valid Bot ID

### Missing config URL

<Frame>
  <img alt="Missing config URL" />

  <img alt="Missing config URL" />
</Frame>

* **Cause**: No configuration URL provided
* **Solution**: Provide a configuration URL

### Invalid config URL

<Frame>
  <img alt="Invalid config URL" />

  <img alt="Invalid config URL" />
</Frame>

* **Cause**: Provided configuration URL is invalid
* **Solution**: Use a valid configuration URL

### Invalid config

<Frame>
  <img alt="Invalid configuration" />

  <img alt="Invalid configuration" />
</Frame>

* **Cause**: Webchat configuration file is malformed
* **Solution**: Fix configuration file format

### Config access denied

<Frame>
  <img alt="Config access denied" />

  <img alt="Config access denied" />
</Frame>

* **Cause**: Access to configuration file is restricted
* **Solution**: Check credentials and URL accessibility

## Bot Errors

### Bot is blocked

<Frame>
  <img alt="Bot is blocked" />

  <img alt="Bot is blocked" />
</Frame>

* **Cause**: Bot has been temporarily paused
* **Solution**: Check your bot's [status](/docs/get-started/manage-your-agent/inspect)

### Quota exceeded

<Frame>
  <img alt="Quota exceeded" />

  <img alt="Quota exceeded" />
</Frame>

* **Cause**: Bot has reached usage limits
* **Solution**: Check usage quotas and limits in [Dashboard](/docs/get-started/configure-your-workspace#manage-usage-quotas)

### Not a participant

<Frame>
  <img alt="Not a participant" />

  <img alt="Not a participant" />
</Frame>

* **Cause**: User not authorized for conversation
* **Solution**: Clear browser storage and refresh

### Invalid message content type

<Frame>
  <img alt="Invalid message content type" />

  <img alt="Invalid message content type" />
</Frame>

* **Cause**: Unable to process message format
* **Solution**
  * Check your bot's logs for any integration errors
  * Start a new conversation

## Network Errors

### Network error

<Frame>
  <img alt="Network error" />

  <img alt="Network error" />
</Frame>

* **Cause**: General network connectivity problems
* **Solution**: Check internet connection

### SSE disconnected

<Frame>
  <img alt="SSE disconnected" />

  <img alt="SSE disconnected" />
</Frame>

* **Cause**: Server-Sent Events connection lost
* **Solution**: Refresh the page


# Listen to events
Source: https://botpress.com/docs/webchat/interact/listen-to-events

Listen for when Webchat opens, closes, raises an error, and more.

You can listen to Webchat events within your website's source code. This is useful if you want to:

* Make your website more responsive to Webchat
* Adjust UI elements depending on Webchat's status
* Handle Webchat errors on your website

## With embedded Webchat

If you added Webchat to your website [using the embed code](/docs/webchat/get-started/quick-start), you can use the [`window.botpress.on`](/docs/webchat/interact/reference#on) method to listen to events.

Just copy and paste any code snippet below into your source code. Then, you can add whatever code you want—it'll execute whenever the event fires.

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Familiarity with JavaScript
</Info>

### Webchat is initialized

This event fires when Webchat has finished loading and is ready to be opened:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:initialized', () => {
	console.log('Webchat has been initialized.');
    // Insert your code here
});
```

This occurs when `window.botpress.init` (the function in the second [inject script](/docs/webchat/get-started/quick-start)) finishes its execution.

### Webchat is ready

This event fires after Webchat has been opened for the first time and is ready to receive messages:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:ready', () => {
	console.log('Webchat has been opened and is ready to receive messages.');
    // Insert your code here
});
```

### Webchat opens

This event fires when the Webchat window is opened:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:opened', () => {
    console.log('Webchat was opened.');
    // Insert your code here
});
```

### Webchat closes

This event fires when the Webchat window is closed:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:closed', () => {
    console.log('Webchat was closed.');
    // Insert your code here
});
```

### New conversation starts

This event fires when a new conversation starts in Webchat:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('conversation', (conversationId) => {
	console.log('Conversation ID: ', conversationId);
    // Insert your code here
});
```

### Message is sent

This event fires when either the user or the bot sends a message:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('message', (message) => {
	console.log('New message: ', message);
    // Insert your code here
});
```

### Error occurs

This event fires when the bot raises an error:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('error', (error) => {
	console.log('Error: ', error);
    // Insert your code here
});
```

### Custom event

This event fires when the bot triggers a custom event:

```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('customEvent', (event) => {
    console.log('Custom event triggered: ', event);
	// Insert your code here
});
```

## With the Webchat React library

<Info>
  You will need:

  * A working React app that [implements Webchat](/docs/webchat/react-library/get-started#step-2%3A-build-a-component)
</Info>

If you're using the [Webchat React library](/docs/webchat/react-library/get-started), you can use the [`useWebchat`](/docs/webchat/react-library/hooks/use-webchat-client) hook's returned `on` value to listen to events. Just add the following code at the top level of your Webchat implementation:

```jsx useWebchat theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { on } = useWebchat({
  clientId: '$CLIENT_ID$'
  // Insert your Client ID here
})
```

Then, paste any of the code snippets below to listen to events. You can add whatever code you want—it’ll execute whenever the event fires.

<Warning>
  The `useWebchat` hook is incompatible with the batteries-included [`<Webchat>` component](/docs/webchat/react-library/components/webchat)—using them together will cause issues and unexpected behaviour.

  If you need to use the hook, make sure you're [manually building Webchat](/docs/webchat/react-library/get-started#option-2%3A-build-webchat-manually).
</Warning>

### New conversation starts

This event fires when a new conversation starts in Webchat:

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('conversation', (conversationId) => {
    console.log('New conversation started:', conversationId)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

### Message is sent

This event fires when either the user or the bot sends a message:

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('message', (message) => {
    console.log('New message:', message)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

### Error occurs

This event fires when the bot raises an error:

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('error', (error) => {
    console.log('Error:', error)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

### Webchat visibility changes

This event fires when you change Webchat's visibility using a [Webchat Card](/docs/studio/concepts/cards/webchat):

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('webchatVisibility', (webchatVisibility) => {
    console.log('Webchat visibility changed:', webchatVisibility)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

### Configuration changes

This event fires when you change Webchat's configuration using the [Configure Webchat](/docs/studio/concepts/cards/webchat#configure-webchat) Card:

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('webchatConfig', (webchatConfig) => {
    console.log('Webchat configuration changed:', webchatConfig)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

### Custom event

This event fires when the bot triggers a custom event:

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('customEvent', (event) => {
    console.log('Custom event triggered:', event)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

### Bot is typing

This event fires when the bot starts/stops typing:

```jsx highlight={4} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
useEffect(() => {
  const unsubscribe = on('isTyping', (status) => {
    console.log('Bot is typing:', status)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```


# Open/close your Webchat
Source: https://botpress.com/docs/webchat/interact/open-close-webchat

Manually open or close Webchat on your website.

You can manually open, close, or toggle the Webchat window using JavaScript methods.

<Tip>
  If you want to open/close your Webchat at a certain point in your Workflow, you can use the [built-in Webchat cards](/docs/studio/concepts/cards/webchat).
</Tip>

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Basic familiarity with JavaScript
</Info>

## Open Webchat

To manually open Webchat:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.open()
```

## Close Webchat

To manually close Webchat:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.close()
```

## Toggle Webchat

To manually toggle Webchat:

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.toggle()
```

This **opens** Webchat if it's closed, or **closes** Webchat if it's open.


# Automatically open Webchat on page load
Source: https://botpress.com/docs/webchat/interact/open-webchat-on-page-load



You can automatically open Webchat when a user visits your website.

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Basic familiarity with JavaScript
</Info>

## On any visit to your website

To open Webchat every time a user visits your website, add the following script to your website's source code:

```javascript index.js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:initialized', (event) => {
  setTimeout(() => {
    window.botpress.open()
  }, 500)
})
```

This waits until [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized), then [opens the Webchat window](/docs/webchat/interact/open-close-webchat#open-webchat).

## On visits with a specific link

You can also use a URL hash (#) to create a custom link that opens Webchat automatically on your website. For example:

* [`botpress.com/docs`](https://botpress.com/docs): Opens the Botpress documentation
* [`botpress.com/docs#ask`](https://botpress.com/docs#ask): Opens the Botpress documentation, then opens Webchat

To create the link, add the following script to your website's source code:

```javascript index.js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:initialized', (event) => {
  setTimeout(() => {
    if (window.location.hash === '#ask') {
      window.botpress.open()
    }
  }, 500)

  window.addEventListener('hashchange', () => {
    if (window.location.hash === '#ask') {
      window.botpress.open()
    }
  })
})
```

This waits until [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized), then [opens the Webchat window](/docs/webchat/interact/open-close-webchat#open-webchat) if the URL contains the `#ask` hash. You can change the hash itself to anything you like.

## Limitation when manually initializing Webchat

If you're manually initializing Webchat, make sure you execute either of the code snippets above before you call `window.botpress.init`:

```javascript index.js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// First, execute this:
window.botpress.init({
  botId: 'xxxxxxxxxxxxxxxxxxxxxx',
  configuration: {
    website: {},
    email: {},
    phone: {},
    termsOfService: {},
    privacyPolicy: {},
    variant: 'soft',
    themeMode: 'light',
    fontFamily: 'inter',
  },
  clientId: 'xxxxxxxxxxxxxxxxxxxxxx',
})

// Then, execute this:
window.botpress.on('webchat:initialized', (event) => {
  setTimeout(() => {
    window.botpress.open()
  }, 500)
})
```

Otherwise, the event listener will miss the initialization event, and Webchat won't open.


# Display proactive bubble
Source: https://botpress.com/docs/webchat/interact/proactive-message-bubble



<Panel>
  <iframe title="Proactive bubble" />

  <iframe title="Message notification" />
</Panel>

You can display a proactive message bubble that encourages users to open Webchat.

<Tip>
  The proactive bubble is just a Webchat UI element—it doesn't count towards any message quotas and isn't associated with any conversation.
</Tip>

<Info>
  You will need:

  * A [Plus plan](https://botpress.com/pricing) or higher
  * A bot that uses a toggle (either the default chat bubble or a [custom toggle](/docs/webchat/interact/use-custom-toggle)). The proactive bubble won't work if you're [embedding Webchat in an element](/docs/webchat/get-started/embedding-webchat)
  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
</Info>

## Setup

1. From your Dashboard, go to your bot's [Webchat configuration settings.](/docs/webchat/get-started/configure-your-webchat)
2. Under **Proactive Message Bubble**, select **Enable**.

## Configuration

After enabling the message bubble, you can configure it using the following settings:

### Proactive message

The proactive message to display to the user.

Defaults to `Hi! 👋 Need help?`

### Trigger type

The event that triggers the proactive bubble:

* **After Delay**: The message will appear after a fixed delay from page load
* **After User Idle**: The message will appear after a fixed delay of user inactivity

<Note>
  If the user interacts with the proactive bubble, it won't re-appear again after the same delay.
</Note>

### Delay time

The time (in seconds) before the proactive bubble appears.


# Webchat methods reference
Source: https://botpress.com/docs/webchat/interact/reference



This page contains a reference for all methods available when [injecting Webchat](/docs/webchat/get-started/quick-start).

***

## `open`

The `window.botpress.open` method opens the Webchat window:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.open();
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

The `open` method takes no parameters.

### Returns

<ResponseField name="" type="void" />

***

## `close`

The `window.botpress.close` method closes the Webchat window:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.close();
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

The `close` method takes no parameters.

### Returns

<ResponseField name="" type="void" />

***

## `toggle`

The `window.botpress.toggle` method toggles the Webchat window open/closed depending on its current state:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.toggle();
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

The `toggle` method takes no parameters.

### Returns

<ResponseField name="" type="void" />

***

## `updateUser`

The asynchronous `window.botpress.updateUser` method updates the data associated with the current Webchat user:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await window.botpress.updateUser({
  name: "<string>",
  pictureUrl: "<string>",
  data: {},
  userKey: "<string>"
});
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

<ResponseField name="user" type="User">
  The user attributes to update.

  <Expandable>
    <ResponseField name="name" type="string">
      A name for the user.
    </ResponseField>

    <ResponseField name="pictureUrl" type="string">
      URL pointing to a picture for the user.
    </ResponseField>

    <ResponseField name="data" type="object">
      An object containing any additional data as key-value pairs. The values can be of any type.
    </ResponseField>

    <ResponseField name="userKey" type="string">
      A custom key to associate with the user.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  By default, the `user` object contains the following properties:

  <ResponseField name="user" type="User">
    <Expandable>
      <ResponseField name="id" type="string">
        Unique identifier for the user.
      </ResponseField>

      <ResponseField name="createdAt" type="string">
        User creation timestamp in ISO 8601 format.
      </ResponseField>

      <ResponseField name="updatedAt" type="string">
        Last user update timestamp in ISO 8601 format.
      </ResponseField>
    </Expandable>
  </ResponseField>

  These are generated by the server and can't be updated or deleted.
</Note>

### Returns

<ResponseField name="" type="Promise<void>">
  A Promise that resolves `void` when the user data has been successfully updated.
</ResponseField>

***

## `getUser`

The asynchronous `window.botpress.getUser` method gets the data associated with the current Webchat user:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await window.botpress.getUser();
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

The `getUser` method takes no parameters.

### Returns

<ResponseField name="" type="Promise<User>">
  A Promise that resolves when the user information has been retrieved.

  <Expandable>
    <ResponseField name="id" type="string">
      Unique identifier for the user.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      User creation timestamp in ISO 8601 format.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Last user update timestamp in ISO 8601 format.
    </ResponseField>

    <ResponseField name="name" type="string">
      A name for the user.
    </ResponseField>

    <ResponseField name="pictureUrl" type="string">
      URL pointing to a picture for the user.
    </ResponseField>

    <ResponseField name="data" type="object">
      An object containing any additional data as key-value pairs. The values can be of any type.
    </ResponseField>

    <ResponseField name="userKey" type="string">
      A custom key to associate with the user.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## `config`

The `window.botpress.config` method updates [Webchat's configuration](/docs/webchat/get-started/configure-your-webchat) and the current user's data.

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.config({
  configuration: {},
  user: {}
});
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

<ResponseField name="" type="object">
  An object containing the Webchat configuration and user data to update.

  <Expandable>
    <ResponseField name="configuration" type="object">
      Webchat configuration settings to update.

      <Expandable>
        <ResponseField name="botName" type="string">
          Name of the bot displayed in the Webchat header.
        </ResponseField>

        <ResponseField name="botAvatar" type="string">
          URL to the bot's avatar image.
        </ResponseField>

        <ResponseField name="botDescription" type="string">
          Description of the bot.
        </ResponseField>

        <ResponseField name="composerPlaceholder" type="string">
          Placeholder text for the message input field.
        </ResponseField>

        <ResponseField name="color" type="string">
          Primary color theme for the Webchat interface as a HEX code.
        </ResponseField>

        <ResponseField name="themeMode" type="string">
          Theme mode. Can be `light` or `dark`.
        </ResponseField>

        <ResponseField name="variant" type="string">
          Visual variant. Can be `solid` or `soft`.
        </ResponseField>

        <ResponseField name="allowFileUpload" type="boolean">
          Whether to enable file upload functionality.
        </ResponseField>

        <ResponseField name="showPoweredBy" type="boolean">
          Whether to show "Powered by Botpress" branding.

          <Warning>
            This setting is deprecated and no longer supported. Use the [`footer`](#param-footer) field instead.
          </Warning>
        </ResponseField>

        <ResponseField name="feedbackEnabled" type="boolean">
          Whether to enable message feedback functionality.
        </ResponseField>

        <ResponseField name="fabImage" type="string">
          URL to the Floating Action Button (FAB) image.
        </ResponseField>

        <ResponseField name="radius" type="number">
          Border radius for the Webchat interface. Must be between 0.5 and 4.
        </ResponseField>

        <ResponseField name="fontFamily" type="string">
          Custom font family for the Webchat interface. Can be one of the default fonts:

          `"inter" | "rubik" | "ibm plex sans" | "fira code"`

          or any [Google Font](https://fonts.google.com/).

          <Warning>
            Google Font titles are case-sensitive.
          </Warning>
        </ResponseField>

        <ResponseField name="additionalStylesheet" type="string">
          Custom CSS styles to apply to the Webchat interface.
        </ResponseField>

        <ResponseField name="additionalStylesheetUrl" type="string">
          URL to an external stylesheet to load for the Webchat interface.
        </ResponseField>

        <ResponseField name="storageLocation" type="string">
          Storage location for webchat data. Can be `localStorage` or `sessionStorage`.
        </ResponseField>

        <ResponseField name="footer" type="string">
          Custom footer content for the Webchat interface. Set to an empty string to remove the footer.

          <Tip>
            You can use Markdown to create links and stylize the footer text.
          </Tip>
        </ResponseField>

        <ResponseField name="headerVariant" type="string">
          Header visual variant. Can be `solid` or `glass`.
        </ResponseField>

        <ResponseField name="adminKey" type="string">
          Admin key for enhanced permissions and functionality.
        </ResponseField>

        <ResponseField name="phone" type="object">
          Phone contact information object.

          <Expandable>
            <ResponseField name="title" type="string">
              Display title for the phone contact.
            </ResponseField>

            <ResponseField name="link" type="string">
              Phone number or link for the contact.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="email" type="object">
          Email contact information object.

          <Expandable>
            <ResponseField name="title" type="string">
              Display title for the email contact.
            </ResponseField>

            <ResponseField name="link" type="string">
              Email address or mailto link for the contact.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="website" type="object">
          Website contact information object.

          <Expandable>
            <ResponseField name="title" type="string">
              Display title for the website contact.
            </ResponseField>

            <ResponseField name="link" type="string">
              Website URL for the contact.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="termsOfService" type="object">
          Terms of service link object.

          <Expandable>
            <ResponseField name="title" type="string">
              Display title for the terms of service link.
            </ResponseField>

            <ResponseField name="link" type="string">
              URL to the terms of service page.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="privacyPolicy" type="object">
          Privacy policy link object.

          <Expandable>
            <ResponseField name="title" type="string">
              Display title for the privacy policy link.
            </ResponseField>

            <ResponseField name="link" type="string">
              URL to the privacy policy page.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <Note>
      If you omit the configuration object or leave any fields blank, they will default to the Webchat configuration set in your Dashboard.
    </Note>

    <ResponseField name="user" type="User">
      User data to update.

      <Expandable>
        <ResponseField name="name" type="string">
          A name for the user.
        </ResponseField>

        <ResponseField name="pictureUrl" type="string">
          URL pointing to a picture for the user.
        </ResponseField>

        <ResponseField name="data" type="object">
          An object containing any additional data as key-value pairs. The values can be of any type.
        </ResponseField>

        <ResponseField name="userKey" type="string">
          A custom key to associate with the user.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Returns

<ResponseField name="" type="void" />

***

## `restartConversation`

The asynchronous `window.botpress.restartConversation` method ends the current conversation and starts a new one:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await window.botpress.restartConversation();
```

It becomes available after [Webchat is ready to receive messages](/docs/webchat/interact/listen-to-events#webchat-is-ready).

### Parameters

The `restartConversation` method takes no parameters.

### Returns

<ResponseField name="" type="Promise<void>">
  A Promise that resolves to `void` when a new conversation has been successfully created.
</ResponseField>

***

## `sendMessage`

The asynchronous `window.botpress.sendMessage` method sends a new message to your bot on behalf of the current user:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await window.botpress.sendMessage("<string>");
```

It becomes available after [Webchat is ready to receive messages](/docs/webchat/interact/listen-to-events#webchat-is-ready).

### Parameters

<ResponseField name="message" type="string">
  The message to send to the bot.
</ResponseField>

### Returns

<ResponseField name="" type="Promise<void>">
  A Promise that resolves to `void` when the message has successfully been sent.
</ResponseField>

***

## `sendEvent`

The asynchronous `window.botpress.sendEvent` method sends a new event to your bot:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await window.botpress.sendEvent({});
```

It becomes available after [Webchat is ready to receive messages](/docs/webchat/interact/listen-to-events#webchat-is-ready).

### Parameters

<ResponseField name="event" type="object">
  An object containing custom data to send to the bot. Can contain any key-value pairs.
</ResponseField>

### Returns

<ResponseField name="" type="Promise<void>">
  A Promise that resolves to `void` when the event has successfully been sent.
</ResponseField>

***

## `setUnreadMessageCount`

The `window.botpress.setUnreadMessageCount` method sets the number of unread messages to display on the Floating Action Button (FAB):

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.setUnreadMessageCount(123);
```

It becomes available after [Webchat has been initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized).

### Parameters

<ResponseField name="count" type="number">
  The number of unread messages to display on the FAB.
</ResponseField>

### Returns

<ResponseField name="" type="void" />

***

## `on`

The `window.botpress.on` method sets up an event listener for a given Webchat event:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('<string>', (event) => {});
```

### Parameters

<ResponseField name="type" type="string">
  The event type to listen for. Can be any of the following event types:

  | Event                 | Description                                                                            |
  | --------------------- | -------------------------------------------------------------------------------------- |
  | `conversation`        | Fires when a new conversation starts                                                   |
  | `message`             | Fires when a message is sent                                                           |
  | `error`               | Fires when an error occurs                                                             |
  | `customEvent`         | Fires for custom events                                                                |
  | `webchat:initialized` | Fires when Webchat has finished loading and is ready to be opened                      |
  | `webchat:ready`       | Fires when Webchat has been opened for the first time and is ready to receive messages |
  | `webchat:opened`      | Fires when Webchat is opened                                                           |
  | `webchat:closed`      | Fires when Webchat is closed                                                           |
  | `*`                   | Fires for any event (receives all events)                                              |
</ResponseField>

<ResponseField name="handler" type="function">
  Callback function that gets called when the event occurs. The function receives event data specific to each event type as its parameter.
</ResponseField>

### Returns

<ResponseField name="" type="function">
  An unsubscribe function that can be called to remove the event listener.
</ResponseField>


# Send custom events from Webchat to your website
Source: https://botpress.com/docs/webchat/interact/send-custom-events/from-webchat

Let your website know when something happens in your user's conversation.

You can send custom events from Webchat to your website. This is useful if you want your website to perform an action when your user reaches a certain point in its conversation with your bot.

<Info>
  You will need:

  * A website with an [embedded bot](webchat/get-started/quick-start)
  * Familiarity with JavaScript
</Info>

<Steps>
  <Step title="Add a Send Custom Event Card">
    In Botpress Studio, add a **Send Custom Event** Card to the Node you want to trigger the event from:

    <Frame>
      <img alt="Send Custom Event Card" />

      <img alt="Send Custom Event Card" />
    </Frame>

    Set the **Conversation ID** to `{{event.conversationId}}`. Then, add any [valid JSON](https://www.w3schools.com/js/js_json_syntax.asp) to the **Event** field.

    The contents of the **Event** field should clearly identify the action you want your website to perform. For example, if you want to checkout with the user's current shopping cart, you could add something like `{"action": "checkout"}`.

    <Tip>
      You can also use [variables](/docs/studio/concepts/variables/) to dynamically insert the contents of the **Event** field.
    </Tip>
  </Step>

  <Step title="React to the event on your website">
    Now, you can react to the event in your website's source code using a [custom event listener](/docs/webchat/interact/listen-to-events/#custom-event).

    ```javascript index.js {3} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    window.botpress.on('customEvent', (event) => {
        console.log('Custom event triggered: ', event);
        // Insert your code here
    });
    ```

    Here, `event` contains whatever data you put in the **Event** field of the **Send Custom Event** Card. You can read its contents if you want your website to react differently depending on which custom event you send. For example:

    ```javascript index.js {3-8} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    window.botpress.on('customEvent', (event) => {  
        console.log('Custom event triggered: ', event);
        if (event.action === "action1") {
            // Handle the first kind of event
        }
        else if (event.action === "action2") {
            // Handle the second kind of event
        }
    });
    ```

    <Tip>
      You can [listen to other kinds of Webchat events](/docs/webchat/interact/listen-to-events), too.
    </Tip>
  </Step>
</Steps>


# Send custom events from your website to Webchat
Source: https://botpress.com/docs/webchat/interact/send-custom-events/to-webchat



You can send custom events from your website to Webchat. This is useful if you want your bot to transition to a certain Node or Workflow when something happens on your website.

## With embedded Webchat

If you added Webchat to your website [using the embed code](/docs/webchat/get-started/quick-start), follow the steps below to send custom events:

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Familiarity with JavaScript
</Info>

<Tip>
  Visual learner? Check out our [YouTube guide](https://www.youtube.com/watch?v=dDGY_wHFt3s\&pp=0gcJCY0JAYcqIYzv) on sending custom events.
</Tip>

<Steps>
  <Step title="Send an event to Webchat">
    First, set up an event to send Webchat from your website's source code. Use the [`window.botpress.sendEvent`](/docs/webchat/interact/reference#sendevent) method:

    ```javascript index.js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    const customPayload = {
        "test": "test"
    }

    window.botpress.sendEvent(customPayload)
    ```

    You can replace the data in `customPayload` with anything you like.
  </Step>

  <Step title="Add a Custom Trigger">
    Next, add a [Custom Trigger](/docs/studio/concepts/triggers#custom-trigger) to your bot's Workflow:

    1. In your Workflow, right-click and select **Trigger**, then **Custom Trigger**:

    <Frame>
      <img alt="Custom Trigger" />

      <img alt="Custom Trigger" />
    </Frame>

    2. In the **Event Filter** field, enter `{{event.payload}}`. This will capture the most recent event you send.
    3. Select **Test**, then **Show last received events**. This will display any events you've sent from your website.
    4. If you've already sent your event, it should show up here. Select **Add as Test**, then **Save**.

    <Warning>
      This step is mandatory. The Custom Trigger won't work until you've successfully tested it.
    </Warning>
  </Step>

  <Step title="Test your trigger">
    Now you can test your Custom Trigger:

    1. Add a transition from the Custom Trigger to another Node. For example:

    <Frame>
      <img alt="Test Trigger" />

      <img alt="Test Trigger" />
    </Frame>

    2. Select the <Icon icon="play" /> button to test the Custom Trigger's behaviour in the Studio's [Emulator](/docs/studio/concepts/emulator).
  </Step>
</Steps>

<Check>
  Once you've re-published your bot, it'll respond to custom events.
</Check>

## With the Webchat React library

If you're using the [Webchat React library](/docs/webchat/react-library/get-started), follow the steps below to send custom events:

<Info>
  You will need:

  * A working React app that [implements Webchat](/docs/webchat/react-library/get-started#step-2%3A-build-a-component)
</Info>

<Steps>
  <Step title="Add the useWebchat hook">
    At the top level of your React component that renders Webchat, add the [`useWebchat`](/docs/webchat/react-library/hooks/use-webchat-client) hook and destructure the `client` object:

    <CodeGroup>
      ```jsx Hook by itself theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      const { client } =
        useWebchat({
          clientId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          // Replace with your actual client ID
      })
      ```

      ```jsx Example in a full React app expandable lines highlight={13-16} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { Fab, Webchat, useWebchat } from '@botpress/webchat'
      import { useState } from 'react'

      function App() {
        const clientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        // Replace with your actual client ID

        const [isWebchatOpen, setIsWebchatOpen] = useState(false)
        const toggleWebchat = () => {
          setIsWebchatOpen((prevState) => !prevState)
        }

        const { client } =
          useWebchat({
            clientId: clientId
          })

        return (
          <>
            <Webchat
              clientId={clientId}
              style={{
                width: '400px',
                height: '600px',
                display: isWebchatOpen ? 'flex' : 'none',
                position: 'fixed',
                bottom: '90px',
                right: '20px',
              }}
            />
            <Fab
              onClick={() => toggleWebchat()}
              style={{
                position: 'fixed',
                bottom: '20px',
                right: '20px',
                width: '64px',
                height: '64px'
              }}
            />
          </>
        )
      }

      export default App
      ```
    </CodeGroup>

    Remember to replace the placeholder `clientId` with your bot's actual client ID.
  </Step>

  <Step title="Send an event to Webchat">
    Now, use the `client` instance to send an event to Webchat. First, define a payload object with any data you'd like. For example:

    ```jsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    const customPayload = {
        "test": "test"
    }
    ```

    Then, send the event using `client.sendEvent(customPayload)`. For example, in a button:

    <CodeGroup>
      ```jsx Send event button theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      <button onClick={() => client.sendEvent(customPayload)}>
        Send custom event
      </button>
      ```

      ```jsx Example in a full React app expandable lines highlight={17-19, 23-25} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { Fab, Webchat, useWebchat } from '@botpress/webchat'
      import { useState } from 'react'

      function App() {
        const clientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        // Replace with your actual client ID
        const [isWebchatOpen, setIsWebchatOpen] = useState(false)
        const toggleWebchat = () => {
          setIsWebchatOpen((prevState) => !prevState)
        }

        const { client } =
          useWebchat({
            clientId: clientId
        })

        const customPayload = {
          "test": "test"
        }

        return (
          <>
            <button onClick={() => client.sendEvent(customPayload)}>
              Send custom event
            </button>
            <Webchat
              clientId={clientId}
              style={{
                width: '400px',
                height: '600px',
                display: isWebchatOpen ? 'flex' : 'none',
                position: 'fixed',
                bottom: '90px',
                right: '20px',
              }}
            />
            <Fab
              onClick={() => toggleWebchat()}
              style={{
                position: 'fixed',
                bottom: '20px',
                right: '20px',
                width: '64px',
                height: '64px'
              }}
            />
          </>
        )
      }

      export default App
      ```
    </CodeGroup>
  </Step>

  <Step title="Add a Custom Trigger">
    Next, add a [Custom Trigger](/docs/studio/concepts/triggers#custom-trigger) to your bot's Workflow:

    1. In your Workflow, right-click and select **Trigger**, then **Custom Trigger**:

    <Frame>
      <img alt="Custom Trigger" />

      <img alt="Custom Trigger" />
    </Frame>

    2. In the **Event Filter** field, enter `{{event.payload}}`. This will capture the most recent event you send.
    3. Select **Test**, then **Show last received events**. This will display any events you've sent from your website.
    4. If you've already sent your event, it should show up here. Select **Add as Test**, then **Save**.

    <Warning>
      This step is mandatory. The Custom Trigger won't work until you've successfully tested it.
    </Warning>
  </Step>

  <Step title="Test your Custom Trigger">
    Now you can test your Custom Trigger:

    1. Add a transition from the Custom Trigger to another Node. For example:

    <Frame>
      <img alt="Test Trigger" />

      <img alt="Test Trigger" />
    </Frame>

    2. Select the <Icon icon="play" /> button to test the Custom Trigger's behaviour in the Studio's [Emulator](/docs/studio/concepts/emulator).
  </Step>
</Steps>

<Check>
  Once you've re-published your bot, it'll respond to custom events.
</Check>


# Send a message from user
Source: https://botpress.com/docs/webchat/interact/send-message



You can programmatically send a message to your bot on the user's behalf using JavaScript.

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Familiarity with JavaScript
</Info>

## Send a message on the user's behalf

To send a message on a user's behalf, use the [`window.botpress.sendMessage`](/docs/webchat/interact/reference#sendmessage) method wrapped in an event listener:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:ready', () => {
  const message = "Hi there!"; // Replace with your own message
  window.botpress.sendMessage(message);
});
```

This snippet:

1. Waits until [Webchat is open and ready to receive messages](/docs/webchat/interact/listen-to-events#webchat-is-ready)
2. Sends the message on behalf of the user

<Note>
  The message won't send until the user has voluntarily opened the Webchat window.
</Note>

## Start the conversation on the user's behalf

To proactively open Webchat and start a conversation on the user's behalf when they visit your website:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:initialized', (event) => {
    window.botpress.open()
})

window.botpress.on('webchat:ready', () => {
    const message = "Hi there!"; // Replace with your own message
    window.botpress.sendMessage(message);
});
```

This snippet:

1. Waits until [Webchat is initialized](/docs/webchat/interact/listen-to-events#webchat-is-initialized)
2. [Opens Webchat](/docs/webchat/interact/open-close-webchat#open-webchat)
3. Waits until [Webchat is ready to receive messages](/docs/webchat/interact/listen-to-events#webchat-is-ready)
4. Sends the message on behalf on the user's behalf


# Send user data
Source: https://botpress.com/docs/webchat/interact/send-user-data

Provide your bot with data about the current user.

You can use Webchat to easily **provide your bot with information about the current user**. This is useful if your website stores user data (like with a customer login) and you want your bot to have access to that data.

Sending user data to your bot allows it to:

* Address the user by name
* Have immediate access to their contact information
* Streamline their experience

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Familiarity with HTML and JavaScript
</Info>

## Update user data

Use the [`window.botpress.updateUser`](/docs/webchat/interact/reference#updateuser) method to update user data after your website has initialized Webchat:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.updateUser({
  data: {
    firstName: newFirstName,
    lastName: newLastName,
    email: newEmail,
  },
})
```

<Warning>
  The `updateUser` method is only available after Webchat has been initialized. To avoid errors, consider [listening for the initialization event](/docs/webchat/interact/listen-to-events#webchat-is-initialized) before calling `updateUser`.
</Warning>

## Initialize with user data

You may want to provide some user data while initializing Webchat on your website. This allows your bot to deliver a more personalized conversation experience from the start.

To provide user data as soon as Webchat is ready, listen for Webchat's initialization event and call [`window.botpress.updateUser`](/docs/webchat/interact/reference#updateuser) as soon as it fires:

```js {3-9} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.on('webchat:initialized', () => {
  console.log('Webchat has been initialized. Loading user...');
  window.botpress.updateUser({
    data: {
      firstName: newFirstName,
      lastName: newLastName,
      email: newEmail,
    },
  })
});
```

## Access user data

You can also retrieve the user data your bot currently has access to:

### In Studio

Once you've provided Webchat with user data, you can use the [Get User Data](/docs/studio/concepts/cards/webchat#get-user-data) Card to access it in the [Studio](/docs/studio/introduction):

<Frame>
  <img alt="Get User Data Card" />

  <img alt="Get User Data Card" />
</Frame>

In the **User ID** field, enter `{{ event.userId }}`. You can store the user data in any variable you'd like.

### On your website

Use the [`window.botpress.getUser`](/docs/webchat/interact/reference#getuser) method to access the current user data programmatically:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
async function getBotpressUser() {
  const user = await window.botpress.getUser()
  console.log(user)
}

getBotpressUser();
```


# Trigger actions when conversation starts
Source: https://botpress.com/docs/webchat/interact/start-trigger



You can make Webchat perform specific actions as soon as a user starts a new conversation. These actions execute before the user sends their first message, making them useful for:

* Sending a welcome message to the user
* Notifying a live agent that a user is chatting with the bot
* Pre-loading any data required for the conversation

<Steps>
  <Step title="Add the Conversation Started Trigger">
    In your Workflow, right-click and select **Trigger**, then **Conversation Started**:

    <Frame>
      <img alt="Conversation Started Trigger" />
    </Frame>

    This will add the **Conversation Started** Trigger to your Workflow.
  </Step>

  <Step title="Setup your Trigger">
    Now, you can add anything you want after your Trigger—it'll execute when a user starts a new conversation:

    <Frame>
      <img alt="Welcome message" />
    </Frame>

    <Note>
      Like other Triggers, **Conversation Started** won't work in the Studio's emulator—you have to test it using Webchat.
    </Note>
  </Step>
</Steps>


# Update Webchat configuration
Source: https://botpress.com/docs/webchat/interact/update-config



You can update your [Webchat's configuration](/docs/webchat/get-started/configure-your-webchat) dynamically using JavaScript. This is useful if you want to update Webchat's style or settings after it's already loaded on your website.

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start)
  * Familiarity with JavaScript
</Info>

## Update configuration

To update Webchat's configuration, you can call the [`window.botpress.config`](/docs/webchat/interact/reference#config) method after Webchat has been initialized:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
window.botpress.config(
  {
    configuration: {},
  }
);
```

Include any [`configuration`](/docs/webchat/interact/reference#param-configuration) object you'd like to apply the new configuration.

<Tip>
  You don't need to provide the entire `configuration` object every time—just the values that you want to update. Any fields you don't include will default to the most recent configuration.
</Tip>

## Switch to dark theme

Here's an example that updates Webchat's theme to dark mode as soon as Webchat loads:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const webchatConfig = {
    "themeMode": "dark",
};

window.botpress.on('webchat:initialized', () => {
    window.botpress.config({ configuration: webchatConfig });
});
```

The above snippet:

1. Waits until [Webchat is initialized](/docs/webchat/interact/listen-to-events#webchat-is-initalized)
2. Updates the [`themeMode`](/docs/webchat/interact/reference#param-theme-mode) configuration to `dark`


# Use custom toggle to open/close Webchat
Source: https://botpress.com/docs/webchat/interact/use-custom-toggle



You can toggle Webchat open/closed using a custom HTML element. This hides the default chat bubble that usually loads with Webchat.

<Info>
  You will need:

  * A website with an [embedded bot](/docs/webchat/get-started/quick-start) using Webchat v3.3
  * Basic familiarity with HTML
</Info>

<Note>
  This option isn't available if you're [embedding Webchat in a specific element](/docs/webchat/get-started/embed-in-element).
</Note>

<Steps>
  <Step title="Get your Webchat element ID">
    First, get your Webchat element ID:

    1. Select your bot from your Workspace.
    2. Go to **Webchat > Deploy Settings**.
    3. Under **Chat Launcher**, select **Custom element**.
    4. Copy the contents of the **Element Selector** field.
       <Tip>
         You can also set a custom element ID in the field.
       </Tip>
    5. Select **Publish Changes**.
  </Step>

  <Step title="Add the element to your website">
    Next, add an element to your website's HTML. Set the `id` attribute to the ID you copied earlier:

    ```html theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    <button id="bp-toggle-chat">Toggle chat</button>
    ```
  </Step>
</Steps>

<Check>
  Done! This element will now toggle the Webchat window.
</Check>


# Display notification bubble
Source: https://botpress.com/docs/webchat/interact/webchat-notification



<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="Message notification" />

      <iframe title="Message notification" />
    </Tab>

    <Tab title="Code">
      <CodeGroup>
        ```html index.html theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        <!DOCTYPE html>
        <html lang="en">
          <head>
            <meta charset="UTF-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <title>Webchat Notification Bubble</title>

            <script src="https://cdn.botpress.cloud/webchat/v3.2/inject.js"></script>
            <script src="https://files.bpcontent.cloud/xxxx/xx/xx/xx/xxxxxxxxxxxxx-xxxxxxxx.js" defer></script>
            <script src="index.js" defer></script>

            <link rel="stylesheet" href="styles.css">
          </head>
          <body>

          <!-- Notification Bubble -->
          <div id="msgDiv" class="cb tri-right btm-right" role="button" tabindex="0" aria-live="polite" aria-label="Notification" style="display:none">
            <span id="msgText"></span>
              <button class="close-chip" type="button" aria-label="Dismiss">×</button>
          </div>

          </body>
        </html>
        ```

        ```js index.js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        function openNotification() {
            if (window.botpress) {
                window.botpress.open();
            } else {
                alert('Botpress integration not available.');
            }
        }

        (function () {
            const msgDiv = document.getElementById('msgDiv');
            const msgText = document.getElementById('msgText');
            const closeBtn = msgDiv?.querySelector('.close-chip');

            function showBubble(text) {
                if (!msgDiv || !msgText) return;

                // Display the notification bubble
                msgText.textContent = text || '';
                msgDiv.style.display = 'block';

                // Avoid stacking handlers on repeated events
                msgDiv.onclick = () => openNotification();

                // Keyboard access
                msgDiv.focus();
                msgDiv.onkeydown = (e) => {
                    if (e.key === 'Enter' || e.key === ' ') {
                        e.preventDefault();
                        openNotification();
                    }
                };

                // Hide the notification bubble if Webchat is opened
                window.botpress.on('webchat:opened', () => {
                    if (msgDiv) msgDiv.style.display = 'none';
                });

                // Optional auto-hide after a period
                setTimeout(() => (msgDiv.style.display = 'none'), 15000);
            }

            // Close/dismiss without action
            if (closeBtn) {
                closeBtn.addEventListener('click', (e) => {
                    e.stopPropagation();
                    msgDiv.style.display = 'none';
                });
            }

            // Extract payload from event
            function extractPayload(raw) {
                let data = raw;

                // If the data is a string
                if (typeof data === 'string') {
                    try { data = JSON.parse(data); } catch { /* ignore */ }
                }

                // Handle both strings and objects as event types
                if (data && typeof data.event === 'string') {
                    try { data = JSON.parse(data.event); } catch { data = { eventType: data.eventType, ...data }; }
                } else if (data && typeof data.event === 'object') {
                    data = data.event;
                }

                return data || {};
            }

            if (window.botpress?.on) {

                // Listen for custom events from the bot
                window.botpress.on('customEvent', (payload) => {
                    const webchat = document.querySelector('iframe[title="Botpress"]');
                    const data = extractPayload(payload);

                    // Show the notification bubble if the Webchat window is closed
                    if (data?.eventType === 'notification' && webchat && webchat.classList.contains('bpClose')) {
                        showBubble(data.message);
                    }
                });
            }
        })();
        ```

        ```css styles.css theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        :root {
          /* Change these to match your page's brand */
          --bubble-bg: #ccddfa;   /* background */
          --bubble-fg: #173569;   /* text */
        }

        .cb {
          position: fixed;
          right: 24px;
          bottom: 102px;
          z-index: 9999;

          display: none; /* shown by JS */
          background: var(--bubble-bg);
          color: var(--bubble-fg);
          border-radius: 16px;
          padding: 14px 42px 14px 16px;
          max-width: 340px;
          line-height: 1.35;
          box-shadow: 0 10px 25px rgba(0, 0, 0, .18);
          cursor: pointer;

          font-family: Roboto, system-ui, -apple-system, Segoe UI, Roboto, "Helvetica Neue", Arial;
          font-size: 15px;
          transition: transform .2s ease, box-shadow .2s ease, opacity .2s ease;
          animation: bubble-in .28s cubic-bezier(.2, .8, .2, 1) both;
        }

        .cb:hover {
          transform: translateY(-1px);
          box-shadow: 0 12px 30px rgba(0, 0, 0, .22);
        }

        .cb:focus {
          outline: none;
        }

        /* Chat tail */
        .tri-right.btm-right::after {
          content: "";
          position: absolute;
          right: 22px;
          bottom: -8px;
          width: 16px;
          height: 16px;
          background: var(--bubble-bg);
          transform: rotate(45deg);
          box-shadow: 0 10px 25px rgba(0, 0, 0, .18);
          border-bottom-right-radius: 4px;
        }

        /* Close chip (optional, inside the bubble) */
        .cb .close-chip {
          position: absolute;
          top: 8px;
          right: 8px;
          width: 26px;
          height: 26px;
          border-radius: 999px;
          background: rgba(255, 255, 255, .18);
          color: var(--bubble-fg);
          border: 0;
          cursor: pointer;
          line-height: 1;
          font-size: 16px;
        }

        .cb .close-chip:hover {
          background: rgba(255, 255, 255, .28);
        }

        @keyframes bubble-in {
          from { transform: translateY(10px) scale(.98); opacity: 0; }
          to   { transform: translateY(0)   scale(1);   opacity: 1; }
        }
        ```
      </CodeGroup>
    </Tab>
  </Tabs>
</Panel>

You can make your website display a notification bubble when your bot sends a new message.

The notification bubble is only displayed if the Webchat window is closed when you receive the message. You can then:

* Open the notification (by clicking it or pressing <kbd>Enter</kbd> / <kbd>Space</kbd>)
* Dismiss the notification (by clicking ×)
* Open Webchat using the FAB (which dismisses the notification automatically)

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * Familiarity with HTML, CSS and JavaScript
</Info>

<Warning>
  Since Webchat uses [Markdown](https://www.markdownguide.org/) for rich text in messages, some messages may not render properly in the notification bubble without further processing.
</Warning>

## Step 1: Add a Hook to your bot

1. In the Studio, navigate to the <Icon icon="anchor" /> [Hooks](/docs/studio/concepts/hooks) section.
2. Select **Create Hook** and set its type to [Before Outgoing](/docs/studio/concepts/hooks#before-outgoing).
3. Paste the following code into the Hook:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await actions.webchat.customEvent({
  conversationId: event.conversationId,
  event: JSON.stringify({
    eventType: 'notification',
    message: outgoingEvent.preview,
  })
})
```

This Hook notifies your website every time your bot sends a new message—that way, your website can display a notification bubble.

## Step 2: Configure your website

Now, you can configure your website to display the notification bubble.

### Add the bubble HTML element

First, add the bubble element somewhere in your website's HTML:

```html theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
<!-- Notification Bubble -->
<div id="msgDiv" class="cb tri-right btm-right" role="button" tabindex="0" aria-live="polite" aria-label="Notification" style="display:none">
  <span id="msgText"></span>
  <button class="close-chip" type="button" aria-label="Dismiss">×</button>
</div>
```

### Add JavaScript

Then, add the following snippet to your website's JavaScript:

```js expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function openNotification() {
    if (window.botpress) {
        window.botpress.open();
    } else {
        alert('Botpress integration not available.');
    }
}

(function () {
    const msgDiv = document.getElementById('msgDiv');
    const msgText = document.getElementById('msgText');
    const closeBtn = msgDiv?.querySelector('.close-chip');

    function showBubble(text) {
        if (!msgDiv || !msgText) return;

        // Display the notification bubble
        msgText.textContent = text || '';
        msgDiv.style.display = 'block';

        // Avoid stacking handlers on repeated events
        msgDiv.onclick = () => openNotification();

        // Keyboard access
        msgDiv.focus();
        msgDiv.onkeydown = (e) => {
            if (e.key === 'Enter' || e.key === ' ') {
                e.preventDefault();
                openNotification();
            }
        };

        // Hide the notification bubble if Webchat is opened
        window.botpress.on('webchat:opened', () => {
            if (msgDiv) msgDiv.style.display = 'none';
        });

        // Optional auto-hide after a period
        setTimeout(() => (msgDiv.style.display = 'none'), 15000);
    }

    // Close/dismiss without action
    if (closeBtn) {
        closeBtn.addEventListener('click', (e) => {
            e.stopPropagation();
            msgDiv.style.display = 'none';
        });
    }

    // Extract payload from event
    function extractPayload(raw) {
        let data = raw;

        // If the data is a string
        if (typeof data === 'string') {
            try { data = JSON.parse(data); } catch { /* ignore */ }
        }

        // Handle both strings and objects as event types
        if (data && typeof data.event === 'string') {
            try { data = JSON.parse(data.event); } catch { data = { eventType: data.eventType, ...data }; }
        } else if (data && typeof data.event === 'object') {
            data = data.event;
        }

        return data || {};
    }

    if (window.botpress?.on) {

        // Listen for custom events from the bot
        window.botpress.on('customEvent', (payload) => {
            const webchat = document.querySelector('iframe[title="Botpress"]');
            const data = extractPayload(payload);

            // Show the notification bubble if the Webchat window is closed
            if (data?.eventType === 'notification' && webchat && webchat.classList.contains('bpClose')) {
                showBubble(data.message);
            }
        });
    }
})();
```

This handles the behaviour of the notification bubble. For example:

* Displays the message received from the event's payload
* Remains visible for 15 seconds before automatically closing
* Can be selected by clicking or pressing <kbd>Enter</kbd> / <kbd>Space</kbd>

<Tip>
  You can configure the behaviour to suit your needs by modifying the code snippet.
</Tip>

### Add CSS

Finally, add this CSS snippet to your website's stylesheet:

```css expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
:root {
  /* Change these to match your page's brand */
  --bubble-bg: #ccddfa;   /* background */
  --bubble-fg: #173569;   /* text */
}

.cb {
  position: fixed;
  right: 24px;
  bottom: 102px;
  z-index: 9999;

  display: none; /* shown by JS */
  background: var(--bubble-bg);
  color: var(--bubble-fg);
  border-radius: 16px;
  padding: 14px 42px 14px 16px;
  max-width: 340px;
  line-height: 1.35;
  box-shadow: 0 10px 25px rgba(0, 0, 0, .18);
  cursor: pointer;

  font-family: Roboto, system-ui, -apple-system, Segoe UI, Roboto, "Helvetica Neue", Arial;
  font-size: 15px;
  transition: transform .2s ease, box-shadow .2s ease, opacity .2s ease;
  animation: bubble-in .28s cubic-bezier(.2, .8, .2, 1) both;
}

.cb:hover {
  transform: translateY(-1px);
  box-shadow: 0 12px 30px rgba(0, 0, 0, .22);
}

.cb:focus {
  outline: none;
}

/* Chat tail */
.tri-right.btm-right::after {
  content: "";
  position: absolute;
  right: 22px;
  bottom: -8px;
  width: 16px;
  height: 16px;
  background: var(--bubble-bg);
  transform: rotate(45deg);
  box-shadow: 0 10px 25px rgba(0, 0, 0, .18);
  border-bottom-right-radius: 4px;
}

/* Close chip (optional, inside the bubble) */
.cb .close-chip {
  position: absolute;
  top: 8px;
  right: 8px;
  width: 26px;
  height: 26px;
  border-radius: 999px;
  background: rgba(255, 255, 255, .18);
  color: var(--bubble-fg);
  border: 0;
  cursor: pointer;
  line-height: 1;
  font-size: 16px;
}

.cb .close-chip:hover {
  background: rgba(255, 255, 255, .28);
}

@keyframes bubble-in {
  from { transform: translateY(10px) scale(.98); opacity: 0; }
  to   { transform: translateY(0)   scale(1);   opacity: 1; }
}
```

You can modify the styling as needed.

<Check>
  Now, your website will display a notification bubble when your bot sends a new message.
</Check>


# Composer
Source: https://botpress.com/docs/webchat/react-library/components/composer



The `Composer` component is where the user writes messages before sending them to the bot. It provides a text area for input, file uploads, and a speech-to-text option.

<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="Composer component" />
    </Tab>

    <Tab title="Code">
      ```jsx App.jsx wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { Composer, useWebchat } from '@botpress/webchat'

      function App() {
        const { client, clientState } = useWebchat({ clientId: '$CLIENT_ID$' }) // Insert your Client ID here

        return (
          <Composer
            disableComposer={false}
            isReadOnly={false}
            allowFileUpload={true}
            connected={clientState !== 'disconnected'}
            sendMessage={client?.sendMessage}
            uploadFile={client?.uploadFile}
            composerPlaceholder="Type a message..."
            showPoweredBy={true}
            footer={'[⚡️ by Botpress](https://botpress.com/?from=webchat)'}
          />
        )
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<Note>
  Although you can use the `Composer` as a standalone component, we recommend using it within the [Container](./container) component and alongside the [Header](./header) and [MessageList](./message-list) components.
</Note>

## Props

<ResponseField name="disableComposer" type="boolean">
  Disables the input field and sending capabilities when set to `true`. Disabling the composer is useful when you want
  to prevent user input temporarily, such as during a loading state or when waiting for a response from the bot.
</ResponseField>

<ResponseField name="isReadOnly" type="boolean">
  Removes the composer completely when set to `true`. This is useful for displaying messages without allowing user
  input.
</ResponseField>

<ResponseField name="allowFileUpload" type="boolean">
  Enables or disables the file upload button.
</ResponseField>

<ResponseField name="connected" type="boolean">
  Indicates whether Webchat is currently connected. When `false`, a modal appears prompting the user to retry by
  reloading the page.
</ResponseField>

<ResponseField name="sendMessage" type="(payload: Message) => void">
  A callback function for sending messages composed by the user.
</ResponseField>

<ResponseField name="uploadFile" type="(file: File) => Promise<{ fileUrl: string; name: string; type: FileType }>">
  Handles the file upload logic and returns file metadata upon success.
</ResponseField>

<ResponseField name="composerPlaceholder" type="string">
  Placeholder text displayed in the input area. Comes from the configuration.
</ResponseField>

<ResponseField name="footer" type="string">
  Displays a footer at the bottom of the Composer.
</ResponseField>

<ResponseField name="inputRef" type="Ref<HTMLTextAreaElement>">
  Provides a ref to the text input element. Useful for focusing or manipulating the input programmatically.
</ResponseField>


# Container
Source: https://botpress.com/docs/webchat/react-library/components/container



The `Container` wraps the core Webchat interface.
It manages:

* Layout
* Drag-and-drop file uploading
* Connection status feedback

It also provides a shared context for nested components like `MessageList` and `Composer`.

<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="Container component" />
    </Tab>

    <Tab title="Code">
      ```jsx App.jsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { Container, useWebchat } from '@botpress/webchat'

      function App() {
        const [isWebchatOpen, setIsWebchatOpen] = useState(false)

        const { clientState } = useWebchat({
          clientId: '$CLIENT_ID$', // Insert your Client ID here
        })

        return (
          <Container
            connected={clientState !== 'disconnected'}
            style={{
              width: '500px',
              height: '800px',
              display: isWebchatOpen ? 'flex' : 'none',
              position: 'fixed',
              bottom: '90px',
              right: '20px',
            }}
          >
            // Your Webchat content goes here
          </Container>
        )
      }
      ```
    </Tab>
  </Tabs>
</Panel>

## Props

<ResponseField name="connected" type="boolean">
  Indicates whether the Webchat is currently connected. When `false`, a modal appears and prompts the user to retry by reloading the page.
</ResponseField>

<ResponseField name="allowFileUpload" type="boolean">
  Controls whether the container has a dropzone for uploading files. Doesn't affect whether the [Composer](/docs/webchat/react-library/components/composer) contains a file upload button.
</ResponseField>


# Floating Action Button
Source: https://botpress.com/docs/webchat/react-library/components/fab



You can use the `Fab` (Floating Action Button) component to toggle the visibility of the Webchat UI in your application.

<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="Fab component" />
    </Tab>

    <Tab title="Code">
      ```jsx App.jsx wrap theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { Fab } from "@botpress/webchat";
      import { useState } from "react";

      function App() {
        const [isWebchatOpen, setIsWebchatOpen] = useState(false);

        return (
          <Fab
            onClick={() => setIsWebchatOpen(isWebchatOpen)}
            style={{
              position: "fixed",
              bottom: "20px",
              right: "20px",
              width: "64px",
              height: "64px",
            }}
          />
        );
      }

      export default App;
      ```
    </Tab>
  </Tabs>
</Panel>

## Props

<ResponseField name="imgUrl" type="string">
  URL to a custom icon image.
</ResponseField>

<ResponseField name="onClick" type="MouseEventHandler<HTMLButtonElement>">
  A callback function triggered when the `Fab` is clicked. Commonly used to toggle the Webchat visibility.
</ResponseField>


# Header
Source: https://botpress.com/docs/webchat/react-library/components/header



The `Header` component sits at the top of the Webchat UI. It displays the bot’s name, avatar, and description. It also provides access to key actions like restarting the conversation or closing the chat window.

<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="Header component" />
    </Tab>

    <Tab title="Code">
      ```jsx App.jsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { Header, useWebchat } from '@botpress/webchat'

      // Every attribute that the header component can take
      const headerConfig = {
        botName: 'SupportBot',
        botAvatar: 'https://cdn.botpress.cloud/bot-avatar.png',
        botDescription: 'Your virtual assistant for all things support.',

        phone: {
          title: 'Call Support',
          link: 'tel:+1234567890',
        },

        email: {
          title: 'Email Us',
          link: 'mailto:support@example.com',
        },

        website: {
          title: 'Visit our website',
          link: 'https://www.example.com',
        },

        termsOfService: {
          title: 'Terms of Service',
          link: 'https://www.example.com/terms',
        },

        privacyPolicy: {
          title: 'Privacy Policy',
          link: 'https://www.example.com/privacy',
        },
      }

      function App() {
        const [isWebchatOpen, setIsWebchatOpen] = useState(false)

        const { newConversation } = useWebchat({
          clientId: '$CLIENT_ID$', // Insert your client id here
        })

        return (
          <Header
            onOpenChange={() => console.log('Override the header open change')}
            defaultOpen={true}
            closeWindow={() => setIsWebchatOpen(false)}
            restartConversation={newConversation}
            disabled={false}
            configuration={headerConfig}
          />
        )
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<Note>
  Although you can use the `Header` as a standalone component, we recommend using it within the
  [Container](./container) component and alongside the [Composer](./composer) and [MessageList](./message-list) components.
</Note>

## Props

<ResponseField name="defaultOpen" type="boolean">
  Controls whether the header is expanded by default. Only used when the `open` prop is uncontrolled.
</ResponseField>

<ResponseField name="open" type="boolean">
  Explicitly controls whether the header is open. Useful for managing the open state from a parent component.
</ResponseField>

<ResponseField name="onOpenChange" type="(open: boolean) => void">
  Callback triggered when the open state changes. It overrides the default behavior of expanding the header. Receives
  the new open state as an argument.
</ResponseField>

<ResponseField name="disabled" type="boolean">
  Disables the header toggle functionality when set to `true`.
</ResponseField>

<ResponseField name="restartConversation" type="() => void">
  Optional function to restart the current conversation. Typically resets the conversation state to the beginning. The
  header must be within a `ModalProvider` for this to work. A  ModalProvider is provided automatically with the
  `Container` component.
</ResponseField>

<ResponseField name="closeWindow" type="() => void">
  Optional function to close the chat window. Useful for embedding scenarios or controlled UIs.
</ResponseField>

<ResponseField name="configuration" type="Pick<Configuration, 'email' | 'phone' | 'privacyPolicy' | 'website' | 'termsOfService' | 'botAvatar' | 'botDescription' | 'botName'>">
  A configuration object containing bot identity and contact details. To enable the expanded header with additional
  links (e.g., website, terms of service), include the following fields: `email`, `phone`, `privacyPolicy`, `website`,
  and `termsOfService`.

  <Expandable>
    <ResponseField name="botName" type="string">
      Name of the bot displayed in the header.
    </ResponseField>

    <ResponseField name="botAvatar" type="string">
      URL to the bot avatar image.
    </ResponseField>

    <ResponseField name="botDescription" type="string">
      Description text shown in the Webchat header.
    </ResponseField>

    <ResponseField name="phone" type="{ title?: string, link?: string }">
      Phone contact information with title and link.
    </ResponseField>

    <ResponseField name="email" type="{ title?: string, link?: string }">
      Email contact information with title and link.
    </ResponseField>

    <ResponseField name="website" type="{ title?: string, link?: string }">
      Website link information with title and URL.
    </ResponseField>

    <ResponseField name="termsOfService" type="{ title?: string, link?: string }">
      Terms of Service link with title and URL.
    </ResponseField>

    <ResponseField name="privacyPolicy" type="{ title?: string, link?: string }">
      Privacy Policy link with title and URL.
    </ResponseField>
  </Expandable>
</ResponseField>


# MessageList
Source: https://botpress.com/docs/webchat/react-library/components/message-list



The `MessageList` component renders the list of messages in the current Webchat conversation.

<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="MessageList component" />
    </Tab>

    <Tab title="Code">
      ```tsx App.tsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
      import { MessageList, useWebchat, Configuration } from '@botpress/webchat'

      const { client, messages, isTyping, user } = useWebchat({
        clientId: '$CLIENT_ID$', // Insert your Client ID here
      })

      const config: Configuration = {
        botName: 'SupportBot',
        botAvatar: 'https://picsum.photos/id/80/400',
        botDescription: 'Your virtual assistant for all things support.',
      }

      const enrichedMessages: RichMessageObject[] = useMemo(
        () =>
          messages.map((message) => {
            const { authorId } = message
            const direction = authorId === user?.id ? 'outgoing' : 'incoming'
            return {
              ...message,
              direction,
              sender:
                direction === 'outgoing'
                  ? { name: user?.name ?? 'You', avatar: user?.pictureUrl }
                  : { name: config.botName ?? 'Bot', avatar: config.botAvatar },
            }
          }),
        [config.botAvatar, config.botName, messages, user?.id, user?.name, user?.pictureUrl]
      )

      function App() {
        return (
          <MessageList
            botAvatar={config.botAvatar}
            botName={config.botName}
            botDescription={config.botDescription}
            isTyping={isTyping}
            showMarquee={true}
            messages={enrichedMessages}
            sendMessage={client?.sendMessage}
          />
        )
      }
      ```
    </Tab>
  </Tabs>
</Panel>

## Props

<Note>
  Although all of the `MessageList` component's props are optional, you need to send the [messages](#messages) prop to display messages.
</Note>

<ResponseField name="botAvatar" type="string">
  The bot’s avatar image URL, used when rendering bot messages or typing indicators.
</ResponseField>

<ResponseField name="botName" type="string">
  The display name of the bot. Also shown in the marquee and typing indicator when no custom sender name is set.
</ResponseField>

<ResponseField name="botDescription" type="string">
  The bot’s short description, used in the marquee area above the message list if enabled.
</ResponseField>

<ResponseField name="isTyping" type="boolean">
  Whether the bot is currently "typing." When `true`, a typing indicator bubble is displayed at the end of
  the message list.
</ResponseField>

<ResponseField name="headerMessage" type="string">
  A message shown at the top of the chat window before any user or bot messages. Useful for welcome or onboarding text.
</ResponseField>

<ResponseField name="messages" type="RichMessageObject[]">
  An array of message objects to render in the chat. Can include standard user (`'outgoing'`) and bot (`'incoming'`) messages, as well as system (`'system'`)
  messages.

  <Warning>
    When using the `MessageList` component, you need to handle the creation of this array yourself. Copy the code example on this page for a working implementation.
  </Warning>
</ResponseField>

<ResponseField name="renderers" type="Partial<Renderers>">
  A mapping of custom message renderers used to override how specific block types are displayed.
</ResponseField>

<ResponseField name="sendMessage" type="(payload: IntegrationMessage) => void">
  A callback function used to send a new message from the message list as a reply.
  This is used by input messages (for example: Button, Dropdown) where the user's input is sent directly from the message list in a message object.
  This means that `sendMessage` is required if your want to use the `Button`, `Dropdown` or any input message types.
</ResponseField>

<ResponseField name="showMarquee" type="boolean">
  Whether to show the bot marquee (bot name, avatar, and description) at the top of the message list. Defaults to
  `true`.
</ResponseField>


# StylesheetProvider
Source: https://botpress.com/docs/webchat/react-library/components/stylesheet-provider



<Panel>
  ```jsx App.jsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  import { StylesheetProvider } from '@botpress/webchat'

  const config = {
    color: '#3778f0',
    fontFamily: 'Inter',
    radius: 1,
    variant: 'soft',
    themeMode: 'light',
    headerVariant: 'solid'
  }

  function App() {
    return (
        <StylesheetProvider
          color={config.color}
          fontFamily={config.fontFamily}
          radius={config.radius}
          variant={config.variant}
          themeMode={config.themeMode}
        />
    )
  }
  ```
</Panel>

The `StylesheetProvider` component dynamically generates and injects a custom Webchat theme based on your configuration.
This includes styling variables like:

* Colors
* Border radius
* Font family
* Theme variant

The generated theme is automatically injected into the page using a `<style>` tag and supports both light and dark modes.

## Props

<ResponseField name="color" type="string">
  Primary theme color in hex format.
</ResponseField>

<ResponseField name="radius" type="number">
  Corner radius for UI elements. Can be `0.5` - `4`
</ResponseField>

<ResponseField name="themeMode" type="'light' | 'dark'">
  Light or dark mode theme.
</ResponseField>

<ResponseField name="variant" type="'solid' | 'soft'">
  Visual style of the chat window.
</ResponseField>

<ResponseField name="fontFamily" type="'rubik' | 'inter' | 'ibm' | 'fira'">
  Font family used in Webchat.
</ResponseField>

<ResponseField name="headerVariant" type="'solid' | 'glass'">
  Style variant of the header.
</ResponseField>


# Webchat
Source: https://botpress.com/docs/webchat/react-library/components/webchat



The `Webchat` component is a batteries-included implementation of the Webchat window. It contains most of what you'd expect when [injecting Webchat](/docs/webchat/get-started/quick-start).

<Panel>
  <Tabs>
    <Tab title="Example">
      <iframe title="Webchat component" />
    </Tab>

    <Tab title="Code">
      <CodeGroup>
        ```jsx App.jsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        import { Fab, Webchat } from '@botpress/webchat'
        import { useState } from 'react'

        function App() {
        const [isWebchatOpen, setIsWebchatOpen] = useState(false)
        const toggleWebchat = () => {
            setIsWebchatOpen((prevState) => !prevState)
        }
        return (
            <>
            <Webchat
                clientId="$CLIENT_ID$" // Your client ID here
                style={{
                width: '400px',
                height: '600px',
                display: isWebchatOpen ? 'flex' : 'none',
                position: 'fixed',
                bottom: '90px',
                right: '20px',
                }}
            />
            <Fab
                onClick={() => toggleWebchat()}
                style={{
                position: 'fixed',
                bottom: '20px',
                right: '20px',
                width: '64px',
                height: '64px'
                }}
            />
            </>
        )
        }

        export default App
        ```
      </CodeGroup>
    </Tab>
  </Tabs>
</Panel>

<Note>
  The `Webchat` component doesn't use the configuration set in your bot's [Dashboard](/docs/webchat/get-started/configure-your-webchat). Instead, configure it using the [configuration](#configuration) prop.
</Note>

<Warning>
  The `<Webchat>` component is incompatible with the [`useWebchat` hook](/docs/webchat/react-library/hooks/use-webchat-client)—using them together will cause issues and unexpected behaviour.

  If you need to use the hook, make sure you're [manually building Webchat](/docs/webchat/react-library/get-started#option-2%3A-build-webchat-manually).
</Warning>

## Props

<ResponseField name="clientId" type="string">
  Your bot's [client ID](/docs/webchat/react-library/get-started#obtain-your-client-id).
</ResponseField>

<ResponseField name="storageKey" type="string">
  Custom key for Webchat's local storage ([if your bot's configuration uses local storage](#param-storage-location))
</ResponseField>

<ResponseField name="user" type="UserCredentials">
  User to load Webchat with.

  <Expandable>
    <ResponseField name="userId" type="string">
      The user's ID.
    </ResponseField>

    <ResponseField name="userToken" type="string">
      The user's token.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conversationId" type="string">
  Conversation ID to load Webchat with.
</ResponseField>

<ResponseField name="configuration" type="Configuration">
  Configuration for Webchat's appearance and style. This object's properties are similar to the Webchat configuration options available in the [Dashboard](/docs/webchat/get-started/configure-your-webchat).

  <Expandable>
    <ResponseField name="botName" type="string">
      Name of the bot displayed in the header.
    </ResponseField>

    <ResponseField name="botAvatar" type="string">
      URL to the bot avatar image.
    </ResponseField>

    <ResponseField name="botDescription" type="string">
      Description text shown in the Webchat header.
    </ResponseField>

    <ResponseField name="fabImage" type="string">
      Image for the [Fab](/docs/webchat/react-library/components/fab).
    </ResponseField>

    <ResponseField name="phone" type="{ title?: string, link?: string }">
      Phone contact information with title and link.
    </ResponseField>

    <ResponseField name="email" type="{ title?: string, link?: string }">
      Email contact information with title and link.
    </ResponseField>

    <ResponseField name="website" type="{ title?: string, link?: string }">
      Website link information with title and URL.
    </ResponseField>

    <ResponseField name="termsOfService" type="{ title?: string, link?: string }">
      Terms of Service link with title and URL.
    </ResponseField>

    <ResponseField name="privacyPolicy" type="{ title?: string, link?: string }">
      Privacy Policy link with title and URL.
    </ResponseField>

    <ResponseField name="composerPlaceholder" type="string">
      Placeholder text for the input composer.
    </ResponseField>

    <ResponseField name="color" type="string">
      Primary theme color in hex format.
    </ResponseField>

    <ResponseField name="radius" type="number">
      Corner radius for UI elements. Can be `0.5` - `4`
    </ResponseField>

    <ResponseField name="themeMode" type="'light' | 'dark'">
      Light or dark mode theme.
    </ResponseField>

    <ResponseField name="variant" type="'solid' | 'soft'">
      Visual style of the chat window.
    </ResponseField>

    <ResponseField name="fontFamily" type="'rubik' | 'inter' | 'ibm' | 'fira'">
      Font family used in Webchat.
    </ResponseField>

    <ResponseField name="showPoweredBy" type="boolean">
      Flag to show or hide the "Powered by Botpress" footer.
    </ResponseField>

    <ResponseField name="additionalStylesheet" type="string">
      Custom inline CSS to apply to the Webchat.
    </ResponseField>

    <ResponseField name="additionalStylesheetUrl" type="string">
      URL pointing to an external stylesheet.
    </ResponseField>

    <ResponseField name="allowFileUpload" type="boolean">
      Flag to enable file uploads in the chat.
    </ResponseField>

    <ResponseField name="storageLocation" type="'localStorage' | 'sessionStorage'">
      Location to store Webchat session data.
    </ResponseField>

    <ResponseField name="footer" type="string">
      Footer content in Markdown.
    </ResponseField>

    <ResponseField name="headerVariant" type="'solid' | 'glass'">
      Style variant of the header.
    </ResponseField>

    <ResponseField name="feedbackEnabled" type="boolean">
      Toggle for user feedback feature.
    </ResponseField>
  </Expandable>
</ResponseField>


# Get started
Source: https://botpress.com/docs/webchat/react-library/get-started

Install the Webchat React library and build your first component.

Botpress offers a **fully customizable React library** that lets you seamlessly add Webchat to your existing React projects.

## Step 1: Installation

<Info>
  You will need:

  * A [published bot](/docs/get-started/quick-start)
  * A [React app](https://react.dev/learn/installation)
</Info>

<Note>
  The Webchat React library requires React 18 or higher. Double-check your project's React version to ensure compatibility.
</Note>

### Install the NPM package

The Webchat library is hosted on `npm`. Download it with your favorite package manager:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  npm install @botpress/webchat
  ```

  ```bash yarn theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  yarn add @botpress/webchat
  ```

  ```bash pnpm theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  pnpm install @botpress/webchat
  ```
</CodeGroup>

### Obtain your Client ID

To integrate the Webchat client into your application, you need to obtain your bot's Client ID.
This ID identifies your bot and enables communication with the Webchat service.

To get your bot's Client ID:

1. From your bot's Dashboard, select your bot.
2. In the left sidebar, go to **Webchat > Features > Advanced Settings**.
3. Select the **Advanced Settings** tab.
4. Copy the **Client ID**.

***

## Step 2: Build a component

The library gives you two options for building a full Webchat experience:

### Option 1: Use the `Webchat` component

The library provides a batteries-included [Webchat](/docs/webchat/react-library/components/webchat) component that contains most of what you'd expect when [injecting Webchat](/docs/webchat/get-started/quick-start).

With this approach, the only other component you need to import is the [Fab](/docs/webchat/react-library/components/fab). Here's an example implementation:

```jsx App.jsx expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Fab, Webchat } from '@botpress/webchat'
import { useState } from 'react'

function App() {
  const [isWebchatOpen, setIsWebchatOpen] = useState(false)
  const toggleWebchat = () => {
    setIsWebchatOpen((prevState) => !prevState)
  }
  return (
    <>
      <Webchat
        clientId="$CLIENT_ID$" // Your client ID here
        style={{
          width: '400px',
          height: '600px',
          display: isWebchatOpen ? 'flex' : 'none',
          position: 'fixed',
          bottom: '90px',
          right: '20px',
        }}
      />
      <Fab
        onClick={() => toggleWebchat()}
        style={{
          position: 'fixed',
          bottom: '20px',
          right: '20px',
          width: '64px',
          height: '64px'
        }}
      />
    </>
  )
}

export default App
```

### Option 2: Build Webchat manually

If you need more customization over each part of the Webchat experience, you can build it manually using the rest of the component library. Here's an example implementation:

```jsx App.jsx expandable theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Container, Header, MessageList, Composer, useWebchat, Fab } from '@botpress/webchat'
import { useState, useMemo } from 'react'

const headerConfig = {
  botName: 'SupportBot',
  botAvatar: 'https://cdn.botpress.cloud/bot-avatar.png',
  botDescription: 'Your virtual assistant for all things support.',

  phone: {
    title: 'Call Support',
    link: 'tel:+1234567890',
  },

  email: {
    title: 'Email Us',
    link: 'mailto:support@example.com',
  },

  website: {
    title: 'Visit our website',
    link: 'https://www.example.com',
  },

  termsOfService: {
    title: 'Terms of Service',
    link: 'https://www.example.com/terms',
  },

    privacyPolicy: {
    title: 'Privacy Policy',
    link: 'https://www.example.com/privacy',
  },
}

function App() {
  const [isWebchatOpen, setIsWebchatOpen] = useState(true)
  const { client, messages, isTyping, user, clientState, newConversation } = useWebchat({
    clientId: '892072aa-0b89-47e0-800c-8da8f387d757', // Insert your Client ID here
  })

  const config = {
    botName: 'SupportBot',
    botAvatar: 'https://picsum.photos/id/80/400',
    botDescription: 'Your virtual assistant for all things support.',
  }
  const enrichedMessages = useMemo(
  () =>
    messages.map((message) => {
      const { authorId } = message
      const direction = authorId === user?.userId ? 'outgoing' : 'incoming'
      return {
        ...message,
        direction,
        sender:
          direction === 'outgoing'
            ? { name: user?.name ?? 'You', avatar: user?.pictureUrl }
            : { name: config.botName ?? 'Bot', avatar: config.botAvatar },
      }
    }),
  [config.botAvatar, config.botName, messages, user?.userId, user?.name, user?.pictureUrl]
  )

  const toggleWebchat = () => {
    setIsWebchatOpen((prevState) => !prevState)
  }

  return (
    <>
    <Container
      connected={clientState !== 'disconnected'}
      style={{
        width: '500px',
        height: '800px',
        display: isWebchatOpen ? 'flex' : 'none',
        position: 'fixed',
        bottom: '90px',
        right: '20px',
      }}
    >
      <Header
        // onOpenChange={() => console.log('Override the header open change')}
        defaultOpen={false}
        closeWindow={() => setIsWebchatOpen(false)}
        restartConversation={newConversation}
        disabled={false}
        configuration={headerConfig}
      />
      <MessageList
        // botAvatar={config.botAvatar}
        botName={config.botName}
        botDescription={config.botDescription}
        isTyping={isTyping}
        headerMessage="Chat History"
        showMarquee={true}
        messages={enrichedMessages}
        sendMessage={client?.sendMessage}
      />
      <Composer
        disableComposer={false}
        isReadOnly={false}
        allowFileUpload={true}
        connected={clientState !== 'disconnected'}
        sendMessage={client?.sendMessage}
        uploadFile={client?.uploadFile}
        composerPlaceholder="Type a message..."
      />
    </Container>
    <Fab onClick={() => toggleWebchat()} style={{ position: 'fixed', bottom: '20px', right: '20px', width: '64px', height: '64px' }}/>
    </>
  )
}

export default App
```

<Check>
  You just built your first Webchat component!
</Check>

## Step 3: Configure Webchat

The `Webchat` component doesn't use the configuration set in your bot's [Dashboard](/docs/webchat/get-started/configure-your-webchat). Instead, follow the steps below to add custom configuration and styles:

### If you're using the `Webchat` component

If you use the batteries-included `Webchat` component, use the [`configuration`](/docs/webchat/react-library/components/webchat#param-configuration) prop to style Webchat.

You can also use any [custom CSS you set in the Dashboard](/docs/webchat/get-started/configure-your-webchat#) by manually passing their URL into the [`additionalStylsheetUrl`](#additionalStylsheetUrl) prop. To get the stylesheet URL:

1. Navigate to your bot's Dashboard.
2. In the left sidebar, navigate to **Files**.
3. Select `webchatAdditionalStyles.css`.
4. Copy the `url`.

### If you're manually building Webchat

If you're manually building Webchat using the component library, use the [`StylesheetProvider`](/docs/webchat/react-library/components/stylesheet-provider) component to style your implementation.

Each component also has various props that you can use for other configuration options—for example, the [`Header`](webchat/react-library/components/header#param-configuration) component's [`configuration`](webchat/react-library/components/header#param-configuration) prop.


# useWebchat
Source: https://botpress.com/docs/webchat/react-library/hooks/use-webchat-client



The `useWebchat` hook provides access to the Webchat client and its state. It allows you to:

* Interact with your bot
* Listen to real-time events
* Manage conversation lifecycle, user info, and messages

<Warning>
  The `useWebchat` hook is incompatible with the batteries-included [`<Webchat>` component](/docs/webchat/react-library/components/webchat)—using them together will cause issues and unexpected behaviour.

  If you need to use the hook, make sure you're [manually building Webchat](/docs/webchat/react-library/get-started#option-2%3A-build-webchat-manually).
</Warning>

## Usage

```tsx App.tsx theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { useWebchat } from '@botpress/webchat'

function App() {
  const { client, clientState, on, user, conversationId, newConversation, messages, isFetchingMessages, isTyping } =
    useWebchat({
      clientId: '$CLIENT_ID$', // Insert your Client ID here
    })
}
```

## Parameters

<ResponseField name="clientId" type="string">
  Your Botpress project Client ID. Required to initialize the client and establish communication with the server.
</ResponseField>

## Returned Values

<ResponseField name="client" type="WebchatClient">
  The underlying client instance. Can be used to manually send events, fetch data, or interact with the server.
</ResponseField>

<ResponseField name="clientState" type="'connecting' | 'connected' | 'error' | 'disconnected'">
  Represents the current connection state of the client.
</ResponseField>

<ResponseField name="on" type="(event: string, callback: Function) => void">
  Allows you to listen to client events such as incoming messages, typing indicators, or custom events.
  Here are the native Webchat events that you can listen to:

  | Events              | Description                                                                   |
  | ------------------- | ----------------------------------------------------------------------------- |
  | `conversation`      | Triggered when a new conversation is started.                                 |
  | `message`           | Triggered when a new message is sent or received.                             |
  | `error`             | Triggered when an error occurs.                                               |
  | `webchatVisibility` | Triggered when the Webchat visibility changes. ('show' or 'hide' or 'toggle') |
  | `webchatConfig`     | Triggered when the Webchat configuration changes.                             |
  | `customEvent`       | Triggered when a custom event is received.                                    |
  | `isTyping`          | Triggered when the bot is typing.                                             |
</ResponseField>

<ResponseField name="user" type="User">
  The current user's profile object:

  ```ts [expandable] theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  const user:
    | {
        name?: string
        pictureUrl?: string
        data?: {
          [k: string]: any
        }
        id: string
        createdAt: string
        updatedAt: string
      }
    | undefined
  ```
</ResponseField>

<ResponseField name="conversationId" type="string">
  The active conversation's unique identifier.
</ResponseField>

<ResponseField name="newConversation" type="() => void">
  A function to start a new conversation. Resets the current chat session.
</ResponseField>

<ResponseField name="messages" type="BlockMessage[]">
  An array of messages for the active conversation. Includes user and bot messages.
</ResponseField>

<ResponseField name="isFetchingMessages" type="boolean">
  Indicates whether messages are currently being fetched from the server.
</ResponseField>

<ResponseField name="isTyping" type="boolean">
  Reflects whether the bot is currently "typing," as indicated by typing events from the server.
</ResponseField>