# Introduction to Studio

Source: https://botpress.com/docs/studio/introduction

Development environment for building AI agents and chatbots.

{/* vale Vale.Spelling["Chatbot", "Chatbots", "chatbot", "chatbots"] = NO */}

[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](/studio/guides/introduction.md).
</Tip>

## Key concepts

<CardGroup cols={3}>
  <Card title="Workflows" icon="workflow" href="/studio/concepts/workflows.md">
    Sequences of steps your bot takes
  </Card>
  <Card title="Nodes" icon="square-mouse-pointer" href="/studio/concepts/nodes/introduction.md">
    Steps in a Workflow
  </Card>
  <Card title="Cards" icon="rows-3" href="/studio/concepts/cards/introduction.md">
    Actions your bot can take within a Node
  </Card>
  <Card title="Knowledge Bases" icon="book-open" href="/studio/concepts/knowledge-base/introduction.md">
    Sources your bot can refer to
  </Card>
  <Card title="Tables" icon="table" href="/studio/concepts/tables.md">
    Local databases for storing information
  </Card>
  <Card title="Variables" icon="variable" href="/studio/concepts/variables/overview.md">
    Containers for storing and reusing data
  </Card>
</CardGroup>

---

# Quickstart

Source: https://botpress.com/docs/studio/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](/tutorial/introduction.md)—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](/webchat/get-started/introduction.md), 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" horizontal href="/webchat/get-started/configure-your-webchat.md">
  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](/studio/introduction.md), 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"
  horizontal
  href="/studio/introduction.md"
>
  Find information about concepts from Botpress Studio
</Card>

<Card
  title="Tutorial"
  icon="chef-hat"
  horizontal
  href="/tutorial/introduction.md"
>
  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.md">
    Use Webchat to embed your bot on your website
  </Card>
  <Card title="Integrate with a channel" icon="plug" href="/integrations/get-started/introduction.md">
    Integrate your bot with another channel or external service
  </Card>
</CardGroup>

<Check>You just built and deployed your first bot with Botpress!</Check>

---

# Preview

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/preview

Test your published agent's behaviour using the built-in preview.

import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'
import Icon from '@/components/Icon.astro'
import Frame from '@/components/Frame.astro'
import Card from '@/components/Card.astro'

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>
  <Picture alt="Preview" class="block dark:hidden" src={previewImg} />
  <Picture alt="Preview" class="hidden dark:block" src={previewDarkImg} />
</Frame>

## Styling

The preview is generated using [Webchat](/webchat/get-started/introduction.md), 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.md" horizontal>
  Configure your agent's appearance using Webchat.
</Card>

---

# Monitor performance

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/monitor

Track conversations, users, and performance analytics for your agent.

import Icon from '@/components/Icon.astro'
import Frame from '@/components/Frame.astro'
import { Badge } from '@/components/ui/badge'

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>
  <Picture alt="Conversation" class="block dark:hidden" src={conversationImg} />
  <Picture alt="Conversation" class="hidden dark:block" src={conversationDarkImg} />
</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>
  <Picture alt="Message JSON data" class="block dark:hidden" src={messageJsonDataImg} />
  <Picture alt="Message JSON data" class="hidden dark:block" src={messageJsonDataDarkImg} />
</Frame>

### AI insights {<Badge variant="deprecated">BETA</Badge>}

Select <Icon icon="sparkles"/> **Enable AI** to enable sentiment analysis and AI summaries for incoming conversations:

<Frame>
  <Picture alt="AI insights" class="block dark:hidden" src={aiInsightsImg} />
  <Picture alt="AI insights" class="hidden dark:block" src={aiInsightsDarkImg} />
</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](/studio/get-started/manage-your-agent/inspect.md#events), or [logs](/studio/get-started/manage-your-agent/inspect.md#logs) associated with that user.

## Analytics

You can view detailed analytics about your agent's performance in the **Analytics** sub-section:

<Frame>
  <Picture alt="Analytics" class="block dark:hidden" src={analyticsImg} />
  <Picture alt="Analytics" class="hidden dark:block" src={analyticsDarkImg} />
</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**

---

# Add knowledge sources

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/knowledge

Add and manage tables and Knowledge Bases for your agent.

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](/studio/concepts/tables.md) 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](/studio/concepts/knowledge-base/introduction.md). This gives you access to advanced options for each [type of source](/studio/concepts/knowledge-base/add-sources.md).

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

---

# Inspect behaviour

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/inspect

View logs, events, files, and errors to debug your agent's behaviour.

import Icon from '@/components/Icon.astro'
import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Logs" class="block dark:hidden" src={logsImg} />
  <Picture alt="Logs" class="hidden dark:block" src={logsDarkImg} />
</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](/studio/guides/advanced/use-code.md)—just use JavaScript's `console.log`:

```js
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 anything that happens within the bot, such as messages from users, bot replies, and system-level occurrences. You can view all incoming events processed by your agent in the **Events** section:

<Frame>
  <Picture alt="Events" class="block dark:hidden" src={eventsImg} />
  <Picture alt="Events" class="hidden dark:block" src={eventsDarkImg} />
</Frame>

### Event data

Select any event to view a detailed JSON representation of all its associated data:

<Frame>
  <Picture alt="Event JSON data" class="block dark:hidden" src={eventJsonDataImg} />
  <Picture alt="Event JSON data" class="hidden dark:block" src={eventJsonDataDarkImg} />
</Frame>

### Quota

Incoming events count towards your plan's Incoming Messages & Events quota. If you need to increase this quota, go to the [Billing](/studio/get-started/configure-your-workspace.md#billing) section.

---

## Files

You can view all files uploaded to your agent in the **Files** section. This includes:

- [Files uploaded by users](/webchat/get-started/configure-your-webchat.md#features)
- Files indexed as part of a [Knowledge Base](/studio/get-started/manage-your-agent/knowledge.md#knowledge-bases)
- System files
- Files you've uploaded yourself using the [Files API](/api-reference/files-api/getting-started.md)

### Inspect file data

Select any file to view a detailed JSON representation of all its associated data:

<Frame>
  <Picture alt="File JSON data" class="block dark:hidden" src={fileJsonDataImg} />
  <Picture alt="File JSON data" class="hidden dark:block" src={fileJsonDataDarkImg} />
</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](/studio/get-started/configure-your-workspace.md#billing) menu.

---

## Issues

You can view any problems or errors your agent encountered in the **Issues** sub-section:

<Frame>
  <Picture alt="Issues" class="block dark:hidden" src={issuesImg} />
  <Picture alt="Issues" class="hidden dark:block" src={issuesDarkImg} />
</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>
  <Picture alt="Issue events" class="block dark:hidden" src={issueEventsImg} />
  <Picture alt="Issue events" class="hidden dark:block" src={issueEventsDarkImg} />
</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

---

# Configure Human Handoff

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/human-handoff

Set up live agent support with the Human-in-the-Loop integration.

import { Tip, Warning } from '@/components/callouts'
import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'
import Icon from '@/components/Icon.astro'
import Frame from '@/components/Frame.astro'
import Card from '@/components/Card.astro'
import { Badge } from '@/components/ui/badge'
import Tooltip from '@/components/Tooltip.astro'

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.md" icon="plug" horizontal>
  Install and configure the official integration{' '}
  <Tooltip tip="This feature requires a Botpress Plus plan or higher.">
    <Badge variant="plus">Plus</Badge>
  </Tooltip>
</Card>

When you've finished setting up the integration, you'll have access to the Human Handoff **Dashboard**.

{/* You can assign members of your Workspace to join conversations that have triggered Human Handoff, and they can directly assist your users. */}

---

## 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>
  <Picture alt="Pending conversation" class="block dark:hidden" src={pendingConversationImg} />
  <Picture alt="Pending conversation" class="hidden dark:block" src={pendingConversationDarkImg} />
</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>
  <Picture alt="Assign conversation" class="block dark:hidden" src={assignConversationImg} />
  <Picture alt="Assign conversation" class="hidden dark:block" src={assignConversationDarkImg} />
</Frame>

Now you can chat directly with the user:

<Frame>
  <Picture alt="Respond to user" class="block dark:hidden" src={respondToUserImg} />
  <Picture alt="Respond to user" class="hidden dark:block" src={respondToUserDarkImg} />
</Frame>

### Close a ticket

{/* vale Vale.Spelling = NO */}
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.
{/* vale Vale.Spelling = YES */}

## Testing

You can test Human Handoff by using your agent's preview to simulate an escalation.

<Steps>
  <Step>Open your agent's [preview](/studio/get-started/manage-your-agent/preview.md).</Step>
  <Step>
    Chat with your agent until it triggers Human Handoff:

    <Frame>
      <Picture
        alt="Trigger Human Handoff"
        class="block dark:hidden"
        src={triggerHumanHandoffImg}
      />
      <Picture
        alt="Trigger Human Handoff"
        class="hidden dark:block"
        src={triggerHumanHandoffDarkImg}
      />
    </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>

---

# Edit appearance

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/edit-appearance

Customize your agent's visual appearance using Webchat.

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.md">
  Check out the Webchat documentation for more information on configuring and styling your agent.
</Card>

---

# Control access to your agent

Source: https://botpress.com/docs/studio/get-started/manage-your-agent/control-access

Restrict which workspace members can access your agent.

import { Info, Note } from '@/components/callouts'
import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'
import Icon from '@/components/Icon.astro'
import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Access control" class="block dark:hidden" src={accessControlImg} />
  <Picture alt="Access control" class="hidden dark:block" src={accessControlDarkImg} />
</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](/studio/get-started/configure-your-workspace.md#manage-roles).

<Note>Workspace owners and administrators always have access to all bots in a workspace.</Note>

---

# Configure your workspace

Source: https://botpress.com/docs/studio/get-started/configure-your-workspace

import { Note, Tip } from '@/components/callouts'
import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'
import Icon from '@/components/Icon.astro'
import Frame from '@/components/Frame.astro'
import Card from '@/components/Card.astro'
import { Badge } from '@/components/ui/badge'
import Tooltip from '@/components/Tooltip.astro'
import Accordion from '@/components/Accordion.astro'
import AccordionGroup from '@/components/AccordionGroup.astro'

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>
  <Picture alt="Home" class="block dark:hidden" src={homeImg} />
  <Picture alt="Home" class="hidden dark:block" src={homeDarkImg} />
</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 {<Tooltip tip='This feature requires a Botpress Plus plan or higher.'><Badge variant="plus">Plus</Badge></Tooltip>}

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](/studio/concepts/workflows.md)) 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](/integrations/get-started/introduction.md).
</Note>

To learn more about building and deploying your own integrations:

<Card title="SDK" icon="hammer" href="/integrations/sdk/overview.md">
  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>
  <Picture alt="Usage" class="block dark:hidden" src={usageImg} />
  <Picture alt="Usage" class="hidden dark:block" src={usageDarkImg} />
</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](/studio/concepts/debugger-logs-json.md#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](/studio/concepts/tables.md).

### 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](/studio/concepts/knowledge-base/introduction.md) 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](/studio/concepts/bot-settings.md#inactivity-timeout)
- Conversations started by [Triggers](/studio/concepts/triggers.md).

### 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" external 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 {<Tooltip tip="This feature requires a Botpress Team plan or higher."><Badge variant="team">Team</Badge></Tooltip>}

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

---

# Home

Source: https://botpress.com/docs/studio/concepts/home

Main menu with global configuration for your bot.

import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

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](/studio/concepts/nodes/autonomous-node.md). 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](/studio/concepts/nodes/autonomous-node.md)
  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>
  <Picture alt="Instructions" class="block dark:hidden" src={homeInstructionsImg} />
  <Picture alt="Instructions" class="hidden dark:block" src={homeInstructionsDarkImg} />
</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>
  <Picture alt="Instructions for Autonomous Node" class="block dark:hidden" src={nodeInstructionsImg} />
  <Picture alt="Instructions for Autonomous Node" class="hidden dark:block" src={nodeInstructionsDarkImg} />
</Frame>

## Knowledge Bases

<Note>
  The **Knowledge Base** section is only available if you have an [Autonomous
  Node](/studio/concepts/nodes/autonomous-node.md) in your bot's main Workflow.
</Note>

You can add [Knowledge Bases](/studio/concepts/knowledge-base/introduction.md) to give your bot sources it can reference when answering questions:

<Frame>
  <Picture alt="Knowledge Bases" class="block dark:hidden" src={knowledgeBaseImg} />
  <Picture alt="Knowledge Bases" class="hidden dark:block" src={knowledgeBaseDarkImg} />
</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](/studio/concepts/nodes/autonomous-node.md) in
  your bot's main Workflow.
</Note>

You can use the **Tools** section to quickly add resources and actions your bot can use:

<Frame>
  <Picture alt="Tools" class="block dark:hidden" src={toolsImg} />
  <Picture alt="Tools" class="hidden dark:block" src={toolsDarkImg} />
</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>
  <Picture alt="Autonomous Node Cards" class="block dark:hidden" src={nodeCardsImg} />
  <Picture alt="Autonomous Node Cards" class="hidden dark:block" src={nodeCardsDarkImg} />
</Frame>

## Communication Channels

<Tip>
  For detailed guides on setting up different channels, check out the [Integrations documentation](/integrations/get-started/introduction.md).
</Tip>

You can deploy your bot in different channels the **Communication Channels** section:

<Frame>
  <Picture alt="Communication Channels" class="block dark:hidden" src={commChannelsImg} />
  <Picture alt="Communication Channels" class="hidden dark:block" src={commChannelsDarkImg} />
</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](/studio/concepts/nodes/autonomous-node.md) in your bot's main Workflow.
</Note>

You can provide feedback on your bot's responses in the [Emulator](/studio/concepts/emulator.md). Then, you can view a summary of your feedback in the **Learning Experiences** section:

<Frame>
  <Picture alt="Learning experiences" class="block dark:hidden" src={learningExperiencesImg} />
  <Picture alt="Learning experiences" class="hidden dark:block" src={learningExperiencesDarkImg} />
</Frame>

---

# Nodes

Source: https://botpress.com/docs/studio/concepts/nodes/introduction

import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

{/* vale Botpress.workflows = NO */}

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>
  <Picture alt="Nodes" class="block dark:hidden" src={nodeImg} />
  <Picture alt="Nodes" class="hidden dark:block" src={nodeDarkImg} />
</Frame>

---

## Overview

An individual Node's behaviour depends on what [Cards](/studio/concepts/cards/introduction.md) 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](/studio/concepts/cards/capture-information.md), [true/false conditions](/studio/concepts/cards/flow-logic.md), 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](/studio/concepts/workflows.md). 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>
  <Picture alt="Transition" class="block dark:hidden" src={transitionImg} />
  <Picture alt="Transition" class="hidden dark:block" src={transitionDarkImg} />
</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](/studio/concepts/emulator.md). 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](/studio/concepts/nodes/autonomous-node.md).</Tip>

### Start Node

The Start Node is the entrance point to every conversation with your bot. It's only available in the [Main Workflow](/studio/concepts/workflows.md#main), can't be modified/deleted, and can't use Cards.

You can select the Start Node to configure:

- Which [Knowledge Base](/studio/concepts/knowledge-base/introduction.md) your bot has access to
- Whether your bot has access to the [Vision Agent](/studio/concepts/agents/vision-agent.md)

### Entry Node

The Entry Node is the start of every Workflow in your bot (except for the [Main Workflow](/studio/concepts/workflows.md#main)). It executes whenever you [transition to a new Workflow](/studio/concepts/workflows.md#transition-to-a-workflow) and can't be deleted.

The only Cards you can add to an Entry Node are:

- [Expression/Intent](/studio/concepts/cards/flow-logic.md) Cards
- [Log](/studio/concepts/cards/utilities.md#log) Cards

<Tip>
  You can toggle variables within an Entry Node—check out the guide to [passing variables between
  Workflows](/studio/concepts/variables/pass-between-workflows.md) for more information.
</Tip>

### Exit Node

The Exit Node is the end of every custom Workflow in your bot ([built-in Workflows](/studio/concepts/workflows.md#built-in-workflows) end with an [End Node](/studio/concepts/nodes/introduction.md#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](/studio/concepts/variables/pass-between-workflows.md) 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](/studio/concepts/workflows.md#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](/studio/concepts/triggers.md).</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](/studio/concepts/workflows.md#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](/studio/concepts/workflows.md#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.

---

# Autonomous Node

Source: https://botpress.com/docs/studio/concepts/nodes/autonomous-node

import Accordion from '@/components/Accordion.astro'
import AccordionGroup from '@/components/AccordionGroup.astro'
import Tab from '@/components/tabs/Tab.astro'
import Tabs from '@/components/tabs/Tabs.astro'
import { Tip, Warning } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

The Autonomous Node **uses AI to make decisions**—like what your bot should say or what tools it should use.

Unlike a [standard Node](/studio/concepts/nodes/introduction.md#standard-node), which executes its [Cards](/studio/concepts/cards/introduction.md) 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>
  <Picture alt="alt" class="block dark:hidden" src={anImg} />
  <Picture alt="alt" class="hidden dark:block" src={anDarkImg} />
</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](/studio/concepts/workflows.md). 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](/studio/concepts/home.md) 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](/studio/concepts/workflows.md) 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](/studio/concepts/variables/overview.md). 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](/studio/concepts/variables/overview.md#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](/studio/concepts/bot-settings.md#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](/studio/concepts/knowledge-base/introduction.md) content

### Enable Vision Agent

You can enable the [Vision Agent](/studio/concepts/agents/vision-agent.md) 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
  ## 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

{/* vale Botpress.workflows = NO */}
Provide clear instructions on how the conversation should flow. This could include:
{/* vale Botpress.workflows = YES */}

- Greeting instructions
- Conditions for [transitioning to sub-Workflows](/studio/concepts/workflows.md#transition-to-a-workflow)
- Closing instructions

<Accordion
title="Example"
>
```markdown Instructions wrap
## 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
  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
  **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](/studio/concepts/variables/scopes/workflow.md), 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
  **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](/studio/concepts/workflows.md#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
    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
  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
  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)](/integrations/integration-guides/hitl/introduction.md) session when the user indicates they'd like to speak to a live agent:

    ```markdown Instructions wrap
    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
## 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](/studio/concepts/emulator.md).
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](/studio/concepts/bot-settings.md#llmz-version).

---

# Cards

Source: https://botpress.com/docs/studio/concepts/cards/introduction

import { Tip, Note } from '@/components/callouts'
import CardGroup from '@/components/CardGroup.astro'
import Card from '@/components/Card.astro'
import Frame from '@/components/Frame.astro'

Cards are drag-and-drop elements that **perform tasks within a [Node](/studio/concepts/nodes/introduction.md)**:

<Frame>
  <Picture alt="Cards" class="block dark:hidden" src={cardsImg} />
  <Picture alt="Cards" class="hidden dark:block" src={cardsDarkImg} />
</Frame>

You can use Cards to:

<CardGroup cols={3}>
  <Card title="Send messages" href="/studio/concepts/cards/send-messages.md">
    Send text, images, and other content to users
  </Card>
  <Card title="Control Workflow logic" href="/studio/concepts/cards/flow-logic.md">
    Transition to another Workflow
  </Card>
  <Card title="Execute code" href="/studio/concepts/cards/execute-code.md">
    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](/integrations/get-started/introduction.md) 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>
  <Picture alt="Card inspector" class="block dark:hidden" src={cardInspectorImg} />
  <Picture alt="Card inspector" class="hidden dark:block" src={cardInspectorDarkImg} />
</Frame>

The Card's configuration fields could be either mandatory or optional—mandatory fields are marked with <span style={{ color: 'rgba(189, 59, 56, 1)' }}>\*</span>.

<Note>
  If no Card is selected, Studio's right panel displays the [Emulator](/studio/concepts/emulator.md). 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](/studio/concepts/nodes/introduction.md#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.

---

# Execute Code

Source: https://botpress.com/docs/studio/concepts/cards/execute-code

import { Note, Warning } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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](/studio/concepts/variables/in-code.md))
- 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](/studio/concepts/actions.md).
</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>
  <Picture alt="Generate code using AI" class="block dark:hidden" src={executeCodeImg} />
  <Picture alt="Generate code using AI" class="hidden dark:block" src={executeCodeDarkImg} />
</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](/studio/concepts/variables/scopes/configuration.md) (use `env` in code), and handle slow or failed requests with `try`/`catch`, timeouts, or fallback flows.

</Note>

---

# 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](/studio/concepts/variables/overview.md#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](/studio/concepts/variables/overview.md#data-types-for-variables) type)
5. Done! You can use this variable in subsequent Cards to access the data.

---

# 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](/studio/concepts/bot-settings.md#inactivity-timeout).

<Tip>
  This Card won't work in the Studio's Emulator. Instead, you can test it using the [shareable Webchat
  link](/studio/get-started/quick-start.md#preview-and-share-your-bot).
</Tip>

## Configuration

<Note>This Card is only available for [Standard Nodes](/studio/concepts/nodes/introduction.md).</Note>

To use the Card, just [add it to any Node in your Workflow](/studio/concepts/cards/introduction.md#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`](/studio/guides/advanced/event-properties.md#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

---

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

---

# Flow Logic

Source: https://botpress.com/docs/studio/concepts/cards/flow-logic

{/* vale Botpress.workflows = NO */}

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](/studio/concepts/variables/scopes/user.md)         | To check a user variable, use **`user.{variable name}`**. <br/>Example: _`user.language` is "English"_                        |
| [Workflow variable](/studio/concepts/variables/scopes/workflow.md) | 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](/studio/concepts/cards/ai/ai-transition.md) 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.

---

# 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](/studio/concepts/cards/ai/ai-task.md)

[AI Transition](/studio/concepts/cards/ai/ai-transition.md)

[AI Generate Text](/studio/concepts/cards/ai/ai-generate-text.md)

---

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

---

# 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
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
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
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
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
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
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></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
{{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
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
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
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
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
;[
  {
    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](/studio/guides/how-to/dropdown-menus.md).
</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.

---

# 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](/studio/guides/how-to/send-reminders.md).</Tip>

## Add the Card

To add the Fixed Schedule Card:

<Steps titleSize="h3">
    <Step title="Open the Trigger menu">
        Right-click anywhere in your Workflow. Then, hover over the Trigger menu:

        ![Trigger menu](./assets/trigger-menu.png)
    </Step>
    <Step title="Add the Fixed Schedule Card">
        Select **Fixed Schedule** to add the Card:

        ![Fixed Schedule Card](./assets/fixed-schedule.png)
    </Step>

</Steps>

## Schedule the Card

You can use the Card's settings to schedule when it executes:

![Fixed Schedule Options](./assets/fixed-schedule-options.png)

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

![cron Settings](./assets/cron-settings.png)

The Card will preview when the trigger is scheduled, or let you know if your cron expression is invalid:

![Invalid cron](./assets/invalid-cron.png)

---

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

---

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

---

# Workflows

Source: https://botpress.com/docs/studio/concepts/workflows

import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

{/* vale Botpress.workflows = NO */}

<Icon icon="workflow" /> Workflows are **sequences of steps that your bot takes**:

<Frame>
  <Picture alt="Workflow" class="block dark:hidden" src={workflowImg} />
  <Picture alt="Workflow" class="hidden dark:block" src={workflowDarkImg} />
</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](/studio/concepts/nodes/introduction.md) 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](/studio/concepts/variables/pass-between-workflows.md)—check out the
  [variables](/studio/concepts/variables/overview.md) section for more information.
</Note>

---

## Built-in Workflows

Every bot comes with a few built-in Workflows to handle specific situations gracefully:

<Frame>
  <Picture alt="Default Workflows" class="block dark:hidden" src={defaultWorkflowsImg} />
  <Picture alt="Default Workflows" class="hidden dark:block" src={defaultWorkflowsDarkImg} />
</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>
  <Picture alt="Main Workflow" class="block dark:hidden" src={mainWorkflowImg} />
  <Picture alt="Main Workflow" class="hidden dark:block" src={mainWorkflowDarkImg} />
</Frame>

Unlike custom Workflows, the Main Workflow always contains:

- A [Start Node](/studio/concepts/nodes/introduction.md#start-node) that starts the conversation
- An [End Node](/studio/concepts/nodes/introduction.md#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>
  <Picture alt="Error Workflow" class="block dark:hidden" src={errorWorkflowImg} />
  <Picture alt="Error Workflow" class="hidden dark:block" src={errorWorkflowDarkImg} />
</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>
  <Picture alt="Timeout Workflow" class="block dark:hidden" src={timeoutWorkflowImg} />
  <Picture alt="Timeout Workflow" class="hidden dark:block" src={timeoutWorkflowDarkImg} />
</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](/studio/concepts/bot-settings.md).</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>
  <Picture alt="Conversation End" class="block dark:hidden" src={endWorkflowImg} />
  <Picture alt="Conversation End" class="hidden dark:block" src={endWorkflowDarkImg} />
</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](/studio/concepts/nodes/introduction.md#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>
  <Picture alt="Workflows section" class="block dark:hidden" src={workflowsMenuImg} />
  <Picture alt="Workflows section" class="hidden dark:block" src={workflowsMenuDarkImg} />
</Frame>

Then, select **Create Workflow** and enter a name for the new Workflow:

<Frame>
  <Picture alt="New Workflow" class="block dark:hidden" src={newWorkflowImg} />
  <Picture alt="New Workflow" class="hidden dark:block" src={newWorkflowDarkImg} />
</Frame>

### From Botpress Hub

You can also browse [Botpress Hub](/integrations/get-started/botpress-hub.md) for user-uploaded Workflows and add them to your bot. Just filter by Workflow to see all available Workflows:

<Frame>
  <Picture alt="Workflows on Hub" class="block dark:hidden" src={workflowsHubImg} />
  <Picture alt="Workflows on Hub" class="hidden dark:block" src={workflowsHubDarkImg} />
</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](/studio/concepts/cards/introduction.md) from the **Flow Logic** section of the Card tray:

<Frame>
  <Picture alt="Flow Logic" class="block dark:hidden" src={flowLogicImg} />
  <Picture alt="Flow Logic" class="hidden dark:block" src={flowLogicDarkImg} />
</Frame>

To transition to a new Workflow, just add it to the Node you want to transition from:

<Frame>
  <Picture alt="Transition Card" class="block dark:hidden" src={transitionCardImg} />
  <Picture alt="Transition Card" class="hidden dark:block" src={transitionCardDarkImg} />
</Frame>

---

## Group Workflows in folders

You can group Workflows into folders to keep them organized:

<Frame>
  <Picture alt="Workflow folders" class="block dark:hidden" src={workflowFoldersImg} />
  <Picture alt="Workflow folders" class="hidden dark:block" src={workflowFoldersDarkImg} />
</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](/integrations/get-started/botpress-hub.md) 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.

---

# Knowledge Bases

Source: https://botpress.com/docs/studio/concepts/knowledge-base/introduction

import { Tip, Note, Warning } from '@/components/callouts'
import CardGroup from '@/components/CardGroup.astro'
import Card from '@/components/Card.astro'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

<Icon icon="book-open" /> Knowledge Bases are **sources of information you provide to your bot**.

<Frame>
  <Picture alt="Knowledge Base" class="block dark:hidden" src={knowledgeBaseImg} />
  <Picture alt="Knowledge Base" class="hidden dark:block" src={knowledgeBaseDarkImg} />
</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](/studio/concepts/tables.md) 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](/studio/concepts/knowledge-base/add-sources.md):

<CardGroup cols={3}>
  <Card title="Websites" icon="app-window" href="/studio/concepts/knowledge-base/add-sources.md#websites" horizontal />
  <Card title="Documents" icon="file-text" href="/studio/concepts/knowledge-base/add-sources.md#documents" horizontal />
  <Card title="Tables" icon="table" href="/studio/concepts/knowledge-base/add-sources.md#tables" horizontal />
  <Card
    title="Search the web"
    icon="search"
    href="/studio/concepts/knowledge-base/add-sources.md#search-the-web"
    horizontal
  />
  <Card title="Rich text" icon="type" href="/studio/concepts/knowledge-base/add-sources.md#rich-text" horizontal />
  <Card
    title="Integrations"
    icon="boxes"
    href="/studio/concepts/knowledge-base/add-sources.md#sources-from-integrations"
    horizontal
  />
</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](/studio/concepts/nodes/autonomous-node.md) or a [Standard Node](/studio/concepts/nodes/introduction.md#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](/studio/concepts/nodes/autonomous-node.md#be-specific).
</Tip>

The default Autonomous Node in a bot's [Main Workflow](/studio/concepts/workflows.md) 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](/studio/concepts/cards/capture-information.md#raw-input)
- A **Query Knowledge Bases** Card

<Warning>
  Both of these Cards require the [Knowledge Agent](/studio/concepts/agents/knowledge-agent.md) 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](/studio/concepts/nodes/autonomous-node.md), 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](/studio/concepts/cards/introduction.md#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](/studio/concepts/cards/introduction.md#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>
  <Picture
    alt="Example instructions for company policy search"
    class="block dark:hidden"
    src={exampleInstructionsPolicyImg}
  />
  <Picture
    alt="Example instructions for company policy search"
    class="hidden dark:block"
    src={exampleInstructionsPolicyDarkImg}
  />
</Frame>

And these instructions for questions about pricing:

<Frame>
  <Picture
    alt="Example instructions for pricing search"
    class="block dark:hidden"
    src={exampleInstructionsPricingImg}
  />
  <Picture
    alt="Example instructions for pricing search"
    class="hidden dark:block"
    src={exampleInstructionsPricingDarkImg}
  />
</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](/studio/concepts/cards/flow-logic.md#transition) Card.
2. In the Card's **Condition** field, paste the following:

```javascript
{
  {
    !event.state.agentVariables.KnowledgeAgent.turn.answer
  }
}
```

3. Add the following to your Autonomous Node's prompt:

```markdown
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](/studio/get-started/configure-your-workspace.md#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](/studio/concepts/debugger-logs-json.md#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](/studio/concepts/nodes/autonomous-node.md#check-the-inspect-window) window to analyze your bot's process when searching Knowledge Bases.

---

# 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 onClick={() => window.botpress.open()}>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](/api-reference/files-api/getting-started.md) 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](/studio/concepts/tables.md) 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](/studio/concepts/tables.md#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](/integrations/get-started/introduction.md) 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](/studio/concepts/cards/introduction.md) that handle synchronization with Knowledge Bases (like the [Google Drive](https://botpress.com/integrations/googledrive) integration)

---

# 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.](/studio/concepts/nodes/autonomous-node.md)

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

---

# Tables

Source: https://botpress.com/docs/studio/concepts/tables

import Accordion from '@/components/Accordion.astro'
import AccordionGroup from '@/components/AccordionGroup.astro'
import Tooltip from '@/components/Tooltip.astro'
import YouTube from '@/components/YouTube.astro'
import { Note, Warning } from '@/components/callouts'

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 id='test' class='transparent-accordion'>
  <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](/studio/concepts/schema.md).

## 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](/studio/concepts/schema.md).

<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](/studio/concepts/cards/execute-code.md#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
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
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
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
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
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
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>
        ✔️
      </td>

      <td>
        ✔️
      </td>
    </tr>

    <tr>
      <td>
        updatedAt
      </td>

      <td>
        date
      </td>

      <td>
        ✔️
      </td>

      <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>
        ✔️
      </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
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
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
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
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
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
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
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
const { table } = await client.updateTable({
  table: 'Data1Table',
  schema: {
    myOldField: null, // Field removal
  },
})
```

#### Renaming the table

A table name must end with "Table".

```javascript
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
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
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
const { table } = await client.deleteTable({ table: 'Data1Table' })
```

## Operations on Tables - via Code

<Picture src={tableCodeOperationsImg} alt="" />

### 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 url="https://www.youtube.com/embed/M0S3r-7FiVk?si=PZc5P9Q2zUHhL5Zq" />

```javascript
// 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 url="https://www.youtube.com/embed/AAUO9p6zniw?si=jSb5DzGAVIyTr2D6" />

```javascript
// 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 url="https://www.youtube.com/embed/8zoqG07tulY?si=DH6GdQ-vuuME207-" />

```javascript
// 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 url="https://www.youtube.com/embed/TsUPf2FwrFY?si=cd19VWqxb5M2mC5R" />

```javascript
// 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
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
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
  { "name": { "$eq": "John" } }
  ```

- `$gt`: Matches values that are greater than a specified value.

  ```json
  { "age": { "$gt": 20 } }
  ```

- `$gte`: Matches values that are greater than or equal to a specified value.

  ```json
  { "age": { "$gte": 20 } }
  ```

- `$lt`: Matches values that are less than a specified value.

  ```json
  { "age": { "$lt": 20 } }
  ```

- `$lte`: Matches values that are less than or equal to a specified value.

  ```json
  { "age": { "$lte": 20 } }
  ```

- `$ne`: Matches all values that aren't equal to a specified value.

  ```json
  { "name": { "$ne": "John" } }
  ```

- `$in`: Matches any of the values specified in an array.

  ```json
  { "name": { "$in": ["Alice", "Bob", "John"] } }
  ```

- `$nin`: Matches none of the values specified in an array.

  ```json
  { "name": { "$nin": ["Alice", "Bob", "John"] } }
  ```

- `$exists`: Matches documents that have the specified field.

  ```json
  { "name": { "$exists": true } }
  ```

- `$mod`: Performs modulo operation on the value of field and matches documents where field % divisor equals the specified remainder.

  ```json
  { "qty": { "$mod": [4, 0] } }
  ```

- `$size`: Matches any document where an array field contains a specified number of elements.

  ```json
  { "tags": { "$size": 3 } }
  ```

- `$regex`: Provides regular expression capabilities for pattern matching strings in queries. It uses a placeholder to prevent SQL injections.

  ```json
  { "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
  { "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
  { "$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
  { "$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
  { "$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
{
   "$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
{
  "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
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 url="https://www.youtube.com/embed/wYpsx6cvT5Q?si=u3YWiDmyasHEed0M" />

```javascript
// 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 url="https://www.youtube.com/embed/zbcTGK8T1PQ?si=fZmhfg7gJVjgsab3" />

```javascript
// 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
// 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
// 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 tip="Happy bot building!">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.

<Picture src={computedColumnSwitchImg} alt="" />

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

<Picture src={tableDependenciesImg} alt="" />

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

<Picture src={editCodeButtonImg} alt="" />

You will see a window with a code editor.

<Picture src={codeEditorImg} alt="" />

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

<Picture src={autoComputeImg} alt="" />

If you don't have **Auto-compute** enabled, a grey icon will appear next to stale table cells.

<Picture src={staleComputeRowImg} alt="" />

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>

---

# Actions

Source: https://botpress.com/docs/studio/concepts/actions

import Tab from '@/components/tabs/Tab.astro'
import Tabs from '@/components/tabs/Tabs.astro'
import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

<Icon icon="bolt" /> Actions are **custom AI-generated tools** you can provide to your bot.

<Tabs>
  <Tab title="Just write your prompt...">
    <Frame>
      <Picture alt="Action prompt" class="block dark:hidden" src={actionPromptImg} />
      <Picture alt="Action prompt" class="hidden dark:block" src={actionPromptDarkImg} />
    </Frame>
  </Tab>
  <Tab title="then use the generated Action.">
    <Frame>
      <Picture alt="Generated action" class="block dark:hidden" src={generatedActionImg} />
      <Picture alt="Actions" class="hidden dark:block" src={generatedActionDarkImg} />
    </Frame>
  </Tab>
</Tabs>

You can use Actions to extend your bot's general functionality beyond what's available with the default [Cards](/studio/concepts/cards/introduction.md) or [integrations](/integrations/get-started/introduction.md). For example:

- Make repeated API calls to an external service
- Perform a specific calculation multiple times
- Manipulate data and [variables](/studio/concepts/variables/overview.md)

<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](/studio/concepts/nodes/autonomous-node.md) calls them.

Just like [Execute Code Cards](/studio/concepts/cards/execute-code.md), 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>
  <Picture alt="Action prompt example" class="block dark:hidden" src={actionPromptExampleImg} />
  <Picture alt="Action prompt example" class="hidden dark:block" src={actionPromptExampleDarkImg} />
</Frame>

Your bot will generate code based on your prompt:

<Frame>
  <Picture alt="Generated Action code" class="block dark:hidden" src={generatedActionCodeImg} />
  <Picture alt="Generated Action code" class="hidden dark:block" src={generatedActionCodeDarkImg} />
</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](/studio/guides/advanced/use-code.md).
</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:

```text
Use the `fetchApiData` Action when you need data from an external API.
```

For more information, check out our guide on prompting your [Autonomous Node](/studio/concepts/nodes/autonomous-node.md#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>
  <Picture alt="Manually provide inputs" class="block dark:hidden" src={manualInputsImg} />
  <Picture alt="Manually provide inputs" class="hidden dark:block" src={manualInputsDarkImg} />
</Frame>

---

## Schemas

Actions use input and output [Schemas](/studio/concepts/schemas.md) 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.

---

# 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](/studio/concepts/agents/policy-agent.md) across your bot's interactions
- Allowing your bot to [communicate in multiple languages](/studio/concepts/agents/translator-agent.md)
- Providing [summaries and transcripts](/studio/concepts/agents/summary-agent.md) of your bot's conversations

## Guides

Select any Agent to learn more about it:

<CardGroup cols={3}>
  <Card title="Summary Agent" href="/studio/concepts/agents/summary-agent.md">
    Condenses the conversation into an AI-generated summary and transcript
  </Card>
  <Card title="Personality Agent" href="/studio/concepts/agents/personality-agent.md">
    Provides your bot with a personality or tone
  </Card>
  <Card title="Policy Agent" href="/studio/concepts/agents/policy-agent.md">
    Enforces business rules and compliance guidelines across your bot's interactions
  </Card>
  <Card title="Translator Agent" href="/studio/concepts/agents/translator-agent.md">
    Allows your bot to communicate in multiple languages
  </Card>
  <Card title="Knowledge Agent" href="/studio/concepts/agents/knowledge-agent.md">
    Retrieves information from the bot's knowledge base
  </Card>
  <Card title="Analytics Agent" href="/studio/concepts/agents/analytics-agent.md">
    Collects, analyzes, and stores data on bot interactions
  </Card>
  <Card title="Vision Agent" href="/studio/concepts/agents/vision-agent.md">
    Adds image recognition and visual processing capabilities to your bot
  </Card>
  <Card title="HITL Agent" href="/studio/concepts/agents/hitl-agent.md">
    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

---

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

---

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

---

# 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}}
```

---

# 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}}
```

---

# 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](/integrations/integration-guides/hitl/introduction.md) 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}}
```

---

# 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](/studio/concepts/nodes/autonomous-node.md#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}}
```

---

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

---

# 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](/studio/concepts/actions.md) and [Execute Code Cards](/studio/concepts/cards/execute-code.md). The key difference is when the code runs: - Actions and Execute Code Cards run at some point in your [Workflow](/studio/concepts/workflows.md). - 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**:

<IncomingEvent />

### After Incoming

This Hook type executes its code after the incoming message has been processed, but before the bot has responded.

**Parameters**:

<IncomingEvent />

### Before Outgoing

This Hook type executes its code before the bot's reply is sent to the user.

**Parameters**:

<IncomingEvent />
<Field name="outgoingEvent" type="IO.OutgoingEvent">
  The message sent by the bot
</Field>

### Before LLMz Execution

This Hook type executes its code before the LLMz engine begins its execution.

**Parameters**:

<IncomingEvent/>
<Field
    name="context"
    type="LLMZ.CreateContext"
>
    The current context provided to the LLMz

    <Expandable>

      <Field
        name="id"
        type="string"
      >
        The unique identifier of the LLMz execution, prefixed with `llmz_`
      </Field>

      <Field
        name="version"
        type="any"
      >
        The version of the LLMz engine or context
      </Field>

      <Field
        name="instructions"
        type="string"
        optional
      >
        Optional instructions provided to guide the LLMz execution
      </Field>

      <Field
        name="objects"
        type="LLMZ.Obj[]"
      >
        A list of objects relevant to the LLMz context
      </Field>

      <Field
        name="tools"
        type="LLMZ.Tool[]"
      >
        A list of tools available for the LLMz engine to use
      </Field>

      <Field
        name="loop"
        type="number"
      >
        The current loop count of the LLMz iteration process
      </Field>

      <Field
        name="temperature"
        type="number"
      >
        The temperature setting used for the LLM model
      </Field>

      <Field
        name="model"
        type="string"
      >
        The name or identifier of the LLM model being used.
      </Field>

      <Field
        name="transcript"
        type="OAI.Message[]"
      >
        The conversation transcript, including all prior messages in the current context
      </Field>

      <Field
        name="location"
        type="LLMZ.Location"
      >
        The current location within the bot's logic
      </Field>
    </Expandable>

</Field>

### After LLMz Execution

This Hook type executes its code after the LLMz engine finishes its execution.

**Parameters**:

<IncomingEvent />
<Field name="execution" type="LLMZ.ExecutionResult">
  The result of the execution
</Field>

### 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**:

<IncomingEvent />
<Field name="iteration" type="LLMZ.IterationResult">
  The result of the iteration
</Field>

### After Conversation End

This Hook type executes after the conversation has **explicitly ended** (transitioned to an [End Node](/studio/concepts/nodes/introduction.md#end-node))

**Parameters**:

<IncomingEvent />

### 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](/studio/guides/how-to/track-ai-spend-in-table.md) for your bot.

**Parameters**:

<IncomingEvent/>
<Field
    name="metadata"
    type="IO.TurnMetadata"
>
    The turn's metadata

    <Expandable>
        <Field
            name="tokens"
            type="IO.TokenReport"
        >
            The token information and cost for the current turn

            <Expandable>
              <Field
                name="summary"
                type="string"
              >
                A summary of the token usage for the last turn
              </Field>
              <Field
                name="details"
                type="string"
              >
                A detailed breakdown of token usage for the last turn
              </Field>
              <Field
                name="billedTokens"
                type="number"
              >
                The number of billed tokens during the last turn
              </Field>
              <Field
                name="usages"
                type="IO.TokenUsage[]"
              >
                An array of token usages

                <Expandable>
                  <Field
                    name="count"
                    type="number"
                  >
                    The number of tokens in the usage
                  </Field>
                  <Field
                    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.
                  </Field>
                  <Field
                    name="duration"
                    type="number"
                  >
                    The duration (in milliseconds) of the usage
                  </Field>
                  <Field
                    name="location"
                    type="string"
                  >
                    The location in the Workflow where the usage occurred
                  </Field>
                  <Field
                    name="cached"
                    type="boolean"
                  >
                    Whether the usage was cached
                  </Field>
                </Expandable>
              </Field>
              <Field
                name="totalTokens"
                type="number"
              >
                The total number of tokens used in the last turn
              </Field>
              <Field
                name="billedTokens"
                type="number"
              >
                The total number of billed tokens used in the last turn
              </Field>
              <Field
                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.
              </Field>
              <Field
                name="savingsPercent"
                type="number"
              >
                The percentage of savings on AI spend for this turn.
              </Field>
            </Expandable>
        </Field>
    </Expandable>

</Field>

## Troubleshooting

If your Hook isn't behaving as expected, you can [check your bot's logs](/studio/concepts/debugger-logs-json.md) to diagnose any problems.

---

# 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 tip="Happy bot building!">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.

---

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

---

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

{/* vale Botpress.workflows = NO */}

- **Ease of Maintenance**: Making it easier to understand and manage data flow within your Botpress application.

{/* vale Botpress.workflows = YES */}

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

<Picture src={inputTypeTextImg} alt="" />

<br />

<Picture src={inputTypeTextAdvanceImg} alt="" />

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

---

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

---

# 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](/studio/concepts/workflows.md#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](/studio/guides/advanced/use-code.md).

### Configuration variables

Here, you can [define and manage configuration variables](/studio/concepts/variables/scopes/configuration.md) for your bot.

## LLM options

In this section, you can configure which Large Language Model (LLM) your bot's [Autonomous Nodes](/studio/concepts/nodes/autonomous-node.md) should use depending on its current task.

<Tip>
  You can [override these settings](/studio/concepts/nodes/autonomous-node.md#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](/studio/concepts/knowledge-base/introduction.md) 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>

---

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

---

# 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](/studio/concepts/variables/scopes/user.md) (for example, their name and address)
- [Persist only throughout a single conversation](/studio/concepts/variables/scopes/conversation.md) (for example, items in a virtual cart)
- [Be safely accessible across all your bot's activity](/studio/concepts/variables/scopes/configuration.md) (for example, API tokens and secrets)

Select any variable scope below to learn more about it:

<CardGroup cols={2}>
  <Card title="Workflow variables" href="/studio/concepts/variables/scopes/workflow.md">
    Only available within the current Workflow
  </Card>
  <Card title="User variables" href="/studio/concepts/variables/scopes/user.md">
    Available for all conversations with a user
  </Card>
  <Card title="Conversation variables" href="/studio/concepts/variables/scopes/conversation.md">
    Only available within the current conversation
  </Card>
  <Card title="Bot variables" href="/studio/concepts/variables/scopes/bot.md">
    Available throughout all your bot's activity
  </Card>
  <Card title="Configuration variables" href="/studio/concepts/variables/scopes/configuration.md">
    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](/studio/concepts/variables/scopes/configuration.md) 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>![Create a variable](./assets/create-variable.png)</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](/studio/concepts/cards/capture-information.md) Card:

<Frame>![Assign a value to a variable](./assets/assign-value.png)</Frame>

<Tip>
  If you want more control over when and how you assign a value to a variable, you can [use code
  instead](/studio/concepts/variables/in-code.md).
</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>

---

# 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](/studio/concepts/workflows.md)**. 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](/studio/concepts/variables/overview.md#variable-scopes).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to
  variables](/studio/concepts/variables/overview.md).
</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>

![Workflow variable in a text card](./assets/workflow-variable-example.png)

</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](/studio/concepts/variables/overview.md#variable-scopes).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to
  variables](/studio/concepts/variables/overview.md).
</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>![User variable in a text card](./assets/user-variable-example.png)</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](/studio/concepts/variables/overview.md#variable-scopes).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to
  variables](/studio/concepts/variables/overview.md).
</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>![Conversation variable in a text card](./assets/conversation-variable-example.png)</Frame>

---

# 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**](/studio/concepts/variables/scopes/configuration.md) instead.

</Warning>

<Tip>
  Need help getting started with variables? Check out our [introduction to
  variables](/studio/concepts/variables/overview.md).
</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>![Bot variable in a text card](./assets/bot-variable-example.png)</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](/studio/concepts/variables/scopes/bot.md), 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](/studio/concepts/variables/scopes/bot.md).
</Note>

<Tip>
  Need help getting started with variables? Check out our [introduction to
  variables](/studio/concepts/variables/overview.md).
</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>![Configuration variables](./assets/configuration-variables.png)</Frame>

3. Select **+**, then enter a **Name** and **Value** for your variable:

<Frame>![Configuration variable fields](./assets/configuration-fields.png)</Frame>

## Read a configuration variable

You can use `env.variablename` to read a configuration variable. For example, in an [Execute Code](/studio/concepts/cards/execute-code.md) Card:

<Frame>![Access configuration variable in an Execute Code Card](./assets/access-config-var.png)</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](/studio/concepts/agents/summary-agent.md). 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](/studio/concepts/agents/knowledge-agent.md)                                                                                                                                                                      |
| `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](/studio/concepts/cards/flow-logic.md#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](/studio/concepts/agents/translator-agent.md)                                                                                                                            |
| `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.                                                                                                                                                                                                                |

---

# Pass variables between Workflows

Source: https://botpress.com/docs/studio/concepts/variables/pass-between-workflows

import Step from '@/components/Step.astro'
import Steps from '@/components/Steps.astro'
import { Note, Check } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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 titleSize="h3">
  <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](/studio/concepts/variables/overview.md#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](/studio/concepts/nodes/introduction.md#entry-node).
    3. Under **Toggle Variables**, select the variable you just created:

    <Frame>
      <Picture
        alt="Toggle input variable"
        class="block dark:hidden"
        src={toggleInputVariableImg}
      />
      <Picture
        alt="Toggle input variable"
        class="hidden dark:block"
        src={toggleInputVariableDarkImg}
      />
    </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>
      <Picture
        alt="Input variable field"
        class="block dark:hidden"
        src={inputVarFieldImg}
      />
      <Picture
        alt="Input variable field"
        class="hidden dark:block"
        src={inputVarFieldDarkImg}
      />
    </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 titleSize="h3">
  <Step title="Pass your output variable">
    1. Select your sub-Workflow's [Exit Node](/studio/concepts/nodes/introduction.md#exit-node).
    2. Under **Toggle Variables**, select the variable you want to pass:

    <Frame>
      <Picture
        alt="Toggle output variable"
        class="block dark:hidden"
        src={toggleOutputVariableImg}
      />
      <Picture
        alt="Toggle output variable"
        class="hidden dark:block"
        src={toggleOutputVariableDarkImg}
      />
    </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>
      <Picture
        alt="Workflow Card"
        class="block dark:hidden"
        src={workflowCardImg}
      />
      <Picture
        alt="Workflow Card"
        class="hidden dark:block"
        src={workflowCardDarkImg}
      />
    </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>
      <Picture
        alt="Read output variable"
        class="block dark:hidden"
        src={readVariableImg}
      />
      <Picture
        alt="Read output variable"
        class="hidden dark:block"
        src={readVariableDarkImg}
      />
    </Frame>

    <Check>
      Your parent Workflow now has access to its sub-Workflow's variable.
    </Check>

  </Step>
</Steps>

---

# 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](/studio/concepts/cards/execute-code.md) 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
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
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
function greetUser(firstName) {
  console.log('Hello, ' + firstName + '!')
}

greetUser(user.firstName)
```

## Combine variables

You might want to combine or concatenate variables.

```javascript
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
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
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)
```                                                                                                                                                                                                  |
````

---

# Triggers

Source: https://botpress.com/docs/studio/concepts/triggers

Triggers are a special kind of [Node](/studio/concepts/nodes/introduction.md) that only **execute when a certain event occurs**. You can recognize Triggers by their distinctive purple colour:

<Frame>![Trigger](./assets/trigger.png)</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](/studio/concepts/cards/capture-information.md) 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](/studio/concepts/cards/introduction.md)** 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>![Add a Trigger](./assets/add-trigger.png)</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>
                ![Conversation Started](./assets/conversation-started.png)
            </Frame>
    </Step>
    <Step title="Configure a test">
        Select **Test** in the bottom-left corner of the Trigger:

            <Frame>
                ![Test Trigger](./assets/test-trigger.png)
            </Frame>

            Then, select **Show last received events**. This will display a list of past events that would set off your Trigger:

            <Frame>
                ![Test events](./assets/test-events.png)
            </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>
                ![Fire Trigger](./assets/fire-trigger.png)
            </Frame>

        Just press the play icon to fire the Trigger. Any logic you have connected to the Trigger will execute in the emulator:

            <Frame>
                ![Trigger fires in emulator](./assets/trigger-emulator.png)
            </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](/webchat/interact/start-trigger.md).
</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>![Welcome message](./assets/welcome-message.png)</Frame>

### Custom Trigger

<Tip>
  For a step-by-step guide to using **Custom Triggers**, check out the [Webchat
  documentation](/webchat/interact/send-custom-events/to-webchat.md).
</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>![Custom Trigger reacting to buttons](./assets/custom-trigger-buttons.png)</Frame>

## Fixed Schedule

<Tip>
  Check out our step-by-step guide on [using the Fixed Schedule Trigger](/studio/concepts/cards/fixed-schedule.md).
</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](/integrations/get-started/introduction.md) 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](/integrations/integration-guides/zendesk.md) comes with two Triggers—**Article Published** and **Article Unpublished**:

<Frame>

![Zendesk Triggers](./assets/zendesk-triggers.png)

</Frame>

---

# Debugger, Logs & JSON

Source: https://botpress.com/docs/studio/concepts/debugger-logs-json

import { Note } from '@/components/callouts'

<Picture src={eventDebuggerLogsJsonImg} alt="" />

## 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](/studio/concepts/cards/execute-code.md) 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
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
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
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](/studio/get-started/manage-your-agent/inspect.md#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](/webchat/get-started/introduction.md) (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](/studio/get-started/configure-your-workspace.md#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](/studio/concepts/workflows.md#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](/studio/concepts/debugger-logs-json.md)'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](/studio/concepts/triggers.md) has fired.
- Conversation ended: The conversation flowed to an End node and has gone through the [Conversation End Workflow](/studio/concepts/workflows.md#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](/studio/concepts/workflows.md#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](/studio/concepts/knowledge-base/introduction.md) and found an answer to the user's question. Clicking it will take you to the [Logs tab](/studio/concepts/debugger-logs-json.md) 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](/studio/concepts/knowledge-base/introduction.md#debugging).

### Execute

- Executing code: The bot is executing some custom code from an [Execute Code card](/studio/concepts/cards/execute-code.md).
- 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.

{/* vale Botpress.workflows = NO */}

### Flow Logic

{/* vale Botpress.workflows = YES */}

- 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](/studio/concepts/cards/capture-information.md) to optionally save it in a [variable](/studio/concepts/variables/overview.md).
- 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](/studio/concepts/cards/capture-information.md#retries).

---

# 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 url="https://www.youtube.com/embed/garalsWay1U?si=S9J8kk6WckEAmxaw" />

---

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

<Picture src={copyToBotImg} alt="" />

---

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

---

# 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](/studio/concepts/emulator.md) 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

<Picture src={studioPreferencesImg} alt="" />

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

---

# 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](/studio/get-started/quick-start.md) 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.

---

# Translate Webchat UI

Source: https://botpress.com/docs/studio/guides/how-to/translate

import { Tip, Check, Info } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

If your bot is having conversations in a language other than English, you can translate its [Webchat](/webchat/get-started/introduction.md) 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](/studio/get-started/quick-start.md)
    - 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](/webchat/get-started/configure-your-webchat.md):

### Name and description

To translate the name and description of your bot, modify the **Bot Name** and **Description** fields:

<Frame>![Translate name and description](./assets/name-and-description.png)</Frame>

### Composer placeholder

To translate the placeholder text in the Composer, modify the **Composer placeholder** field:

<Frame>![Translate composer placeholder](./assets/translate-composer.png)</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](/webchat/get-started/configure-your-webchat.md).
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](/webchat/get-started/configure-your-webchat.md#use-custom-styles).
</Tip>

### New conversation modal

You can translate the modal that appears when a user restarts a conversation:

<Frame>![New conversation modal](./assets/new-convo-modal.png)</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}
/* 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>![Today label](./assets/today-label.png)</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}
/* 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>
  <Picture alt="Delivery status" class="block dark:hidden" src={deliveryStatusImg} />
  <Picture alt="Delivery status" class="hidden dark:block" src={deliveryStatusDarkImg} />
</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}
.bpReset .bpMessageDeliveryStatus::after {
  content: 'Envoyé'; /* Replace this with your own translation*/
}
```

---

# Send reminders to conversations

Source: https://botpress.com/docs/studio/guides/how-to/send-reminders

import { Check, Info } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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](/studio/get-started/quick-start.md)

</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](/studio/concepts/variables/scopes/configuration.md#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](/studio/concepts/cards/fixed-schedule.md) Trigger to your bot's [Workflow](/studio/concepts/workflows.md). This will make sure your reminder sends on a set interval.

<Frame>
  <Picture alt="Fixed Schedule Trigger" class="block dark:hidden" src={fixedScheduleImg} />
  <Picture alt="Fixed Schedule Trigger" class="hidden dark:block" src={fixedScheduleDarkImg} />
</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](/studio/concepts/cards/execute-code.md) Card to your Trigger:

<Frame>
  <Picture alt="Execute code" class="block dark:hidden" src={executeCodeImg} />
  <Picture alt="Execute code" class="hidden dark:block" src={executeCodeDarkImg} />
</Frame>

## Step 4: Apply the custom code

Paste the following code into the Card's configuration:

```javascript
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>

---

# Use different LLM for Autonomous Nodes

Source: https://botpress.com/docs/studio/guides/how-to/different-an-models

import { Check, Info, Warning } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Icon from '@/components/Icon.astro'

<Warning>
  You can now [override default LLMs directly in your Autonomous Node's settings](/studio/concepts/nodes/autonomous-node.md#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](/studio/concepts/nodes/autonomous-node.md) to use a different LLM than the default model specified in your [Bot Settings](/studio/concepts/bot-settings.md#autonomous-language-model). This is useful if your bot needs a higher-performing model for certain tasks.

<Info>

You will need:

- A [published bot](/studio/get-started/quick-start.md)
- A [Workflow](/studio/concepts/workflows.md) 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](/studio/concepts/emulator.md).
2. Continue until the bot transitions to the Autonomous Node whose model you want to change:

<Frame>
  <Picture alt="Transition to new Autonomous Node" class="block dark:hidden" src={anTransitionImg} />
  <Picture alt="Transition to new Autonomous Node" class="hidden dark:block" src={anTransitionDarkImg} />
</Frame>

3. Select one of your messages from after the bot transitioned to the new Autonomous Node. Then, open the [JSON tab](/studio/concepts/debugger-logs-json.md#json) in the bottom panel.
4. Under **Payload**, navigate to `state > context`:

<Frame>
  <Picture alt="Current Workflow and Node IDs" class="block dark:hidden" src={currentIdsImg} />
  <Picture alt="Current Workflow and Node IDs" class="hidden dark:block" src={currentIdsDarkImg} />
</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>
  <Picture alt="GPT 4.1" class="block dark:hidden" src={gpt41Img} />
  <Picture alt="GPT 4.1" class="hidden dark:block" src={gpt41DarkImg} />
</Frame>

## Step 2: Add a Hook to change models

1. In the Studio, navigate to the <Icon icon="anchor"/> [Hooks](/studio/concepts/hooks.md) section.
2. Select **Create Hook** and set its type to [Before LLMz Execution](/studio/concepts/hooks.md#before-llmz-execution).
3. Paste the following code into the Hook:

```js {6-7,15}
// 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](/studio/concepts/bot-settings.md#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](/studio/concepts/debugger-logs-json.md) after transitioning to the Autonomous Node in the Emulator:

<Frame>
  <Picture alt="Model change logs" class="block dark:hidden" src={modelChangeLogsImg} />
  <Picture alt="Model change logs" class="hidden dark:block" src={modelChangeLogsDarkImg} />
</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.

---

# Track AI spend in a table

Source: https://botpress.com/docs/studio/guides/how-to/track-ai-spend-in-table

import { Check, Info, Warning } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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](/studio/concepts/nodes/autonomous-node.md)
- [AI Cards](/studio/concepts/cards/ai/introduction.md)
- Queries to a [Knowledge Base](/studio/concepts/knowledge-base/introduction.md)

<Info>
    You will need:

    - A [published bot](/studio/get-started/quick-start.md)

</Info>

## Step 1: Create a table

1. [Create a new table](/studio/concepts/tables.md#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>
  <Picture alt="Table" class="block dark:hidden" src={tableImg} />
  <Picture alt="Table" class="hidden dark:block" src={tableDarkImg} />
</Frame>

## Step 2: Add a Hook to track AI spend

1. [Create a new Hook](/studio/concepts/hooks.md#add-a-hook) with the type [After Turn End](/studio/concepts/hooks.md#after-turn-end).
2. Paste the following code into the Hook:

```javascript
// 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>
  <Picture alt="Table with AI spend" class="block dark:hidden" src={tableFullImg} />
  <Picture alt="Table with AI spend" class="hidden dark:block" src={tableFullDarkImg} />
</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](/studio/concepts/hooks.md#add-a-hook) with the type [After Conversation End](/studio/concepts/hooks.md#after-conversation-end).
4. Paste the following code into the Hook:

```javascript
// 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](/studio/concepts/workflows.md), the conversation will only end when it [times out](/studio/concepts/bot-settings.md#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>

---

# 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](/studio/concepts/cards/capture-information.md) and an approach using code when you need a dropdown with fewer than six options.

<Info>
    You will need:

    - A [published bot](/studio/get-started/quick-start.md)
    - 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](/webchat/get-started/quick-start.md)'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](/integrations/get-started/introduction.md) section for more
  information.
</Warning>

## Method 1: Automatic dropdown (Capture Information)

1. Add a [Capture Information](/studio/concepts/cards/capture-information.md) Card to your [Workflow](/studio/concepts/workflows.md). 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](/studio/concepts/cards/capture-information.md#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](/studio/concepts/cards/execute-code.md) Card.

### Send the dropdown message

```javascript
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](/studio/guides/advanced/event-properties.md).
</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](/studio/concepts/cards/capture-information.md#wait-for-user-input) Card so the Workflow pauses until the user interacts

2. Use an [Expression Card](/studio/concepts/cards/flow-logic.md#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
   workflow.varName = event.payload.value
   ```

   Remember to [create a Workflow variable](/studio/concepts/variables/scopes/workflow.md) (for example `varName`, type **String**) and grant access in code as needed ([variables in code](/studio/concepts/variables/in-code.md)).

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](/webchat/get-started/configure-your-webchat.md#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
/* 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>

---

# 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](/studio/guides/advanced/event-properties.md) 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](/studio/concepts/actions.md)                       | When an [Autonomous Node](/studio/concepts/nodes/autonomous-node.md) 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](/studio/concepts/cards/execute-code.md) | At a specific point in a [Workflow](/studio/concepts/workflows.md)                                                    | ❌       | Perform a one-time operation on some data provided by a user                  |
| [Hooks](/studio/concepts/hooks.md)                           | 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](/studio/concepts/actions.md) are reusable code snippets that only [Autonomous Nodes](/studio/concepts/nodes/autonomous-node.md) 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](/studio/concepts/cards/execute-code.md) execute a one-time piece of code at some point in a [Workflow](/studio/concepts/workflows.md). 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](/studio/concepts/hooks.md) 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](/api-reference.md).                | 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>

---

# Event Properties

Source: https://botpress.com/docs/studio/guides/advanced/event-properties

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](/studio/guides/advanced/use-code.md). This includes:

- [Hooks](/studio/concepts/hooks.md)
- [Actions](/studio/concepts/actions.md)
- [Execute Code Cards](/studio/concepts/cards/execute-code.md)

You can also access the `event` object within certain [Cards](/studio/concepts/cards/introduction.md)' configuration fields.

<Warning>
  This documentation omits certain properties of the `event` object which exist to maintain internal functionality and
  aren't useful for <Tooltip tip="Happy bot building!">bot builders</Tooltip>.
</Warning>

<IncomingEvent />

---

# 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**

<Picture src={workflowExampleImg} alt="" />

### 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**

<Picture src={improperWorkflowExitImg} alt="" />

---

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

---

# 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 tip="Happy bot building!">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 {<Tooltip tip="This feature requires a Botpress Team plan or higher."><span class="inline-flex items-center rounded-full border border-emerald-500/30 bg-emerald-50 px-2 py-0.5 text-xs font-medium text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-300">Team</span></Tooltip>}

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 {<Tooltip tip="This feature requires a Botpress Team plan or higher."><span class="inline-flex items-center rounded-full border border-emerald-500/30 bg-emerald-50 px-2 py-0.5 text-xs font-medium text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-300">Team</span></Tooltip>}

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](/studio/get-started/configure-your-workspace.md#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>

---

# 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

<Picture src={botConfigurationImg} alt="" />

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

<Picture src={ragSafetyImg} alt="" />

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

{/* vale Botpress.workflows = NO */}

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

{/* vale Botpress.workflows = YES */}

### LLM Inspector

<Picture src={llmInspectorImg} alt="" />

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

<Picture src={hitlImg} alt="" />

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.

---

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

---

# Raw Conversations

Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/exporting-raw-conversations-with-the-botpress-api

Access and export raw bot conversations from Botpress to an external service using 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](/studio/get-started/manage-your-agent/monitor.md#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
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
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](/api-reference/pagination.md) 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
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
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
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
[
  {
    "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
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
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

Retrieve and export conversation history from within your Botpress bot to external services.

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](/studio/concepts/agents/summary-agent.md) 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](/studio/concepts/hooks.md) 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](/studio/guides/advanced/exporting-data/exporting-raw-conversations-with-the-botpress-api.md)

## Using Hooks

[Hooks](/studio/concepts/hooks.md) 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](/studio/guides/advanced/exporting-data/exporting-raw-conversations-with-the-botpress-api.md)

### Setting up the Hooks

1. Create a hook under "Before Incoming Message" in the "Hooks" section with the following code:

```ts
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
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](/studio/concepts/cards/execute-code.md) to manipulate the variable as you prefer, for example sending it to an API or via email:

```ts
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](/studio/concepts/workflows.md#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>

---

# Streaming Analytics

Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/streaming-analytics-from-within-your-bot-with-hooks

Stream in-depth bot analytics from Botpress to third-party services like Segment or Amplitude using 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
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
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>

---

# Compiled Bot Analytics

Source: https://botpress.com/docs/studio/guides/advanced/exporting-data/exporting-compiled-bot-analytics-with-the-botpress-api

Export compiled bot analytics from Botpress to your own database or third-party service using 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
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
[
  {
    "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](/studio/concepts/hooks.md) to export the data in real-time to a third-party service like Mixpanel, Hotjar, Segment or Amplitude.

---

# 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](/studio/guides/advanced/exporting-data/streaming-analytics-from-within-your-bot-with-hooks.md) 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](/studio/guides/advanced/event-properties.md) 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
// 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"`.

---

# Advanced Starter Template

Source: https://botpress.com/docs/studio/guides/advanced/kitchen-sink-advanced-starter-template

import YouTube from '@/components/YouTube.astro'

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

<Picture src={downloadStartGithubImg} alt="" />

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

<Picture src={importBotImg} alt="" />

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 url="https://www.youtube.com/embed/-N4OoKg_w4I?si=0OrPkHzFgHqbAmvF" />

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

---

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

---

# 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](/studio/concepts/debugger-logs-json.md#logs)                             | 30 days                                                                                                         |                                                                                                 |
| [Conversations](/studio/get-started/manage-your-agent/monitor.md#conversations) | 90 days                                                                                                         | Can be manually deleted using the [Chat API](/api-reference/chat-api/openapi/deleteConversation.md) |
| [Messages](/studio/get-started/manage-your-agent/monitor.md#conversations)      | 90 days                                                                                                         | Can be manually deleted using the [Chat API](/api-reference/chat-api/openapi/deleteMessage.md)      |
| [Events](/studio/get-started/manage-your-agent/inspect.md#events)               | 90 days                                                                                                         |                                                                                                 |
| Files                                                                        | Indefinitely, unless [created with an expiry date](/api-reference/files-api/openapi/upsertFile.md#body-expires-at) | Can be manually deleted using the [Files API](/api-reference/files-api/openapi/deleteFile.md)       |

<Note>Other types of data are kept indefinitely unless you [delete them using one of our APIs](/api-reference.md).</Note>

---

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

---

# Quickstart

Source: https://botpress.com/docs/viber/get-started/quickstart

Build, test, publish, and embed your first Botpress Viber agent through conversation.

[Botpress Viber](https://viber.botpress.cloud) is a conversational builder for creating, testing, and launching AI agents. Describe what you want your agent to do, and **Vibe**, its builder agent, helps you create and improve it.

<Frame>
  <Picture alt="The Viber home screen where you describe the agent you want to build" src={viberHomeImg} />
</Frame>

## Create your first agent

<Steps>

<Step title="Describe the agent you want">

Open [Botpress Viber](https://viber.botpress.cloud), select a workspace, and choose **New agent**.

Tell Vibe:

- who the agent should help;
- what the agent should help them accomplish;
- what information the agent should know; and
- any tools or human handoff behavior it needs.

For example:

> Build a customer support agent for Northstar. It should answer questions about shipping and returns using our help center and escalate billing disputes to a person.

Start with what you know. Vibe may ask follow-up questions before creating the first version of your agent.

</Step>

<Step title="Refine what Vibe built">

Continue working with Vibe in the same conversation. You can ask it to change the agent's behavior, add knowledge, connect tools, or prepare it for a channel.

For example:

- "Make the responses concise and friendly."
- "Use this page to answer questions about our return policy."
- "Escalate refund requests over $500 to a person."

You can also open the screens under **Build** to review or edit the agent's behavior, knowledge, tools, and escalation settings directly.

<Frame>
  <Picture alt="Configuring Acme Support's tone, response length, and greeting" class="block dark:hidden" src={builderOverviewImg} />
  <Picture alt="Configuring Acme Support's tone, response length, and greeting" class="hidden dark:block" src={builderOverviewDarkImg} />
</Frame>

</Step>

<Step title="Test the agent">

Open **Preview** and have a representative conversation with your agent. Preview runs your latest changes, including changes you have not published yet.

If the agent responds incorrectly, describe the problem to Vibe or use **Fix with Vibe**. Test the conversation again after Vibe applies the change.

<Frame>
  <div class="relative aspect-[16/10] w-full overflow-hidden">
    <Picture alt="Flagging an inaccurate Acme Support answer in Preview" class="absolute inset-0 h-full w-full object-cover object-[45%_50%] dark:hidden" src={previewFixImg} />
    <Picture alt="Flagging an inaccurate Acme Support answer in Preview" class="absolute inset-0 hidden h-full w-full object-cover object-[45%_50%] dark:block" src={previewFixDarkImg} />
  </div>
</Frame>

</Step>

<Step title="Publish and add Webchat to your website">

Select **Publish changes** and publish the agent. New agents start with Webchat enabled, so you can publish without connecting another channel.

After publishing:

1. Open **Deploy > Channels > Webchat**.
2. Select **Share your agent**.
3. Copy the embed snippet.
4. Paste the snippet immediately before the closing `</body>` tag on your website.

Use the shareable link when you want to test the published agent in another browser or send it to someone for review.

<Info>The embedded and hosted Webchat run the published version. Publish again whenever you want them to receive your latest changes.</Info>

<Frame>
  <div class="relative aspect-[16/10] w-full overflow-hidden">
    <Picture alt="Copying the Acme Support Webchat embed snippet" class="absolute inset-0 h-full w-full object-cover object-[44%_50%] dark:hidden" src={webchatEmbedImg} />
    <Picture alt="Copying the Acme Support Webchat embed snippet" class="absolute inset-0 hidden h-full w-full object-cover object-[44%_50%] dark:block" src={webchatEmbedDarkImg} />
  </div>
</Frame>

</Step>

</Steps>

<Check>Your first Viber agent is live.</Check>

## Explore Viber

<CardGroup cols={3}>
  <Card title="Define behavior" icon="scroll-text" href="/viber/build/behavior.md">
    Define your agent's role, Instructions, Playbooks, memory, safety, and escalation rules.
  </Card>
  <Card title="Add knowledge" icon="database" href="/viber/build/knowledge.md">
    Give your agent reliable information from websites, FAQs, files, and web search.
  </Card>
  <Card title="Connect tools" icon="blocks" href="/viber/build/tools-and-integrations.md">
    Connect integrations, HTTP APIs, and MCP tools that let your agent take action.
  </Card>
  <Card title="Test and improve" icon="play" href="/viber/test-and-improve.md">
    Use Preview, simulations, conversations, and gaps to improve your agent.
  </Card>
  <Card title="Connect channels" icon="radio" href="/viber/deploy/channels.md">
    Make your agent available through Webchat, messaging, voice, and SMS channels.
  </Card>
  <Card title="Publish and share" icon="send" href="/viber/deploy/publish-and-share.md">
    Publish your changes, then embed Webchat on your website or share its hosted link.
  </Card>
</CardGroup>

---

# How Viber works

Source: https://botpress.com/docs/viber/get-started/how-viber-works

Understand the people, product areas, and terminology used in Botpress Viber.

Botpress Viber separates building, testing, deployment, and improvement into distinct areas. Understanding how those areas relate makes it easier to describe changes to Vibe and verify the resulting agent.

## Viber, Vibe, and your agent

These terms refer to different parts of the experience:

| Term | Function |
| --- | --- |
| **Botpress Viber** | The conversational builder where you create, test, publish, and improve an agent. **Viber** is the short form used throughout these docs. |
| **Vibe** | The builder agent inside Viber. Vibe translates your requests into structured agent configuration and helps you refine it. |
| **Your agent** | The customer-facing agent you build and publish. It answers users through channels and acts through its configured tools. |

<Info>When these docs say **agent**, they mean the customer-facing agent you are building, not Vibe.</Info>

## Application areas

The Viber navigation organizes work by function:

| Area | Function |
| --- | --- |
| **Overview** | Review the agent summary and manage its display name and avatar. |
| **Preview** | Have a conversation with the current working version before publishing it. |
| **Build** | Define what the agent knows, how it behaves, and which actions it can take. |
| **Deploy** | Configure the channels where users can talk to the published agent. |
| **Monitor** | Review tests and conversations, identify problems, and decide what to improve. |

Vibe remains available alongside these areas. You can describe a change conversationally, then open the relevant screen to review or refine the resulting configuration.

<Frame>
  <Picture alt="The Viber navigation and Instructions screen for Acme Support" class="block dark:hidden" src={builderOverviewImg} />
  <Picture alt="The Viber navigation and Instructions screen for Acme Support" class="hidden dark:block" src={builderOverviewDarkImg} />
</Frame>

## Build

The **Build** group contains the agent's configuration:

| Screen | Function |
| --- | --- |
| **Instructions** | Rules that apply throughout conversations, organized into Identity, Communication, Memory, and Safety. |
| **Playbooks** | Reusable procedures for specific goals, multi-step tasks, or conditional behavior. |
| **Knowledge** | Websites, FAQs, files, and web results the agent can search when answering. |
| **Tools** | Integrations, HTTP requests, and MCP tools the agent can use to act in external systems. |
| **Escalation** | Conditions and procedures for handing a conversation to a person. |

Instructions and Playbooks define the agent's behavior and when it should use Tools or Escalation. The agent searches its prepared Knowledge when that information is relevant to a conversation.

## Deploy

The **Deploy** group contains **Channels**. A channel is where users talk to the published agent, such as Webchat or a connected messaging provider.

Channels are different from tools. A channel carries conversations between users and the agent. A tool lets the agent perform an action in another system.

## Monitor

The **Monitor** group contains the evidence you use to improve the agent:

| Screen | Function |
| --- | --- |
| **Conversations** | Review conversations from Preview and connected channels. |
| **Simulations** | Run repeatable question and flow tests. |
| **Gaps** | Review identified weaknesses and send actionable corrections to Vibe. |

## From request to published agent

Changes move through Viber in a consistent loop:

1. Describe the desired result to Vibe or edit the relevant screen directly.
2. Viber updates the working version of the agent.
3. Test the working version in Preview or Simulations.
4. Publish the verified working version.
5. Users interact with the published version through connected channels.
6. Review Conversations, Simulations, and Gaps, then refine the agent again.

Publishing does not create a second agent. It promotes the working version to the version used by connected channels. Later changes remain in the working version until you publish again.

<div
  role="img"
  aria-label="Describe or edit the agent, test the working version, publish it to connected channels, then review and refine it"
  class="not-prose my-6 flex flex-wrap items-center gap-2"
>
  <div class="rounded-lg border border-stone-200 bg-white px-4 py-3 text-sm font-medium text-stone-900 dark:border-stone-700 dark:bg-stone-900 dark:text-stone-100">Describe or edit</div>
  <span aria-hidden="true" class="text-stone-400">→</span>
  <div class="rounded-lg border border-stone-200 bg-white px-4 py-3 text-sm font-medium text-stone-900 dark:border-stone-700 dark:bg-stone-900 dark:text-stone-100">Working version</div>
  <span aria-hidden="true" class="text-stone-400">→</span>
  <div class="rounded-lg border border-stone-200 bg-white px-4 py-3 text-sm font-medium text-stone-900 dark:border-stone-700 dark:bg-stone-900 dark:text-stone-100">Test</div>
  <span aria-hidden="true" class="text-stone-400">→</span>
  <div class="rounded-lg border border-stone-200 bg-white px-4 py-3 text-sm font-medium text-stone-900 dark:border-stone-700 dark:bg-stone-900 dark:text-stone-100">Publish</div>
  <span aria-hidden="true" class="text-stone-400">→</span>
  <div class="rounded-lg border border-stone-200 bg-white px-4 py-3 text-sm font-medium text-stone-900 dark:border-stone-700 dark:bg-stone-900 dark:text-stone-100">Connected channels</div>
  <span aria-hidden="true" class="text-stone-400">→</span>
  <div class="rounded-lg border border-stone-200 bg-white px-4 py-3 text-sm font-medium text-stone-900 dark:border-stone-700 dark:bg-stone-900 dark:text-stone-100">Review and refine, then repeat</div>
</div>

## Core distinctions

Keep these concepts separate when working in Viber:

- **Vibe and your agent:** Vibe builds and changes the configuration. Your agent uses that configuration in customer conversations.
- **Instructions and Playbooks:** Instructions are always-on rules. Playbooks are procedures for specific situations.
- **Channels and tools:** Channels carry conversations. Tools perform actions.
- **Working and published versions:** Preview and Simulations use the working version. Connected channels use the published version.
- **Viber and Studio:** Viber does not use Studio nodes, cards, or visual workflows. A Viber Playbook is not a Studio workflow.
- **Viber and the ADK:** Viber does not require a TypeScript project or the ADK development model.

<LinkCard
  href="/viber/build/behavior.md"
  title="Define agent behavior"
  description="Configure Instructions, Playbooks, tools, and escalation behavior."
  icon="scroll-text"
/>

---

# Define agent behavior

Source: https://botpress.com/docs/viber/build/behavior

Configure identity, Instructions, Playbooks, memory, safety, and human handoff.

## How behavior works

An agent's behavior is built in layers. Instructions define the rules that always apply, Playbooks define reusable procedures, and Escalation defines when a human should take over.

You can ask Vibe to update any of these layers or edit them directly in Viber. Review the structured screen after a conversational edit so you know what will run.

## Instructions

Open **Build > Instructions** to define behavior that should apply throughout every conversation.

| Tab | What it controls |
| --- | --- |
| **Identity** | The agent's role, responsibilities, and scope. |
| **Communication** | Tone, style, and how the agent should present information. |
| **Memory** | What the agent can retain about a user across conversations. |
| **Safety** | Boundaries and rules the agent must follow. |

<Info>The agent's display name and avatar are configured on **Overview**. The Identity tab under Instructions defines the agent's role and scope.</Info>

Keep Instructions focused on durable rules. If a behavior depends on an ordered series of steps, branching conditions, or a reusable procedure, model it as a Playbook instead.

## Playbooks

A **Playbook** describes a multi-step or conditional procedure the agent can follow. Examples include qualifying a lead, troubleshooting a problem, collecting order details, or completing a refund request.

| Use Instructions when | Use a Playbook when |
| --- | --- |
| A rule should apply to every conversation. | A procedure applies to a specific goal or situation. |
| The behavior is about identity, tone, memory, or safety. | The behavior requires ordered steps or conditions. |
| A short instruction is sufficient. | The procedure should be reused, tested, and improved independently. |

A Playbook is not required for every agent. Direct Instructions are enough for simple, always-on behavior.

## Use tools in behavior

Reference a connected tool action where the agent should use it:

- A tool referenced in global Instructions is available even when no Playbook is active.
- When a Playbook is active, its referenced tools are added to the globally referenced tools.

Connecting an integration alone does not tell the agent when to call an action. Add the action to the relevant Instructions or Playbook and explain the condition for using it.

<Tip>
  Use Viber's slash-command picker when editing Instructions, Playbooks, or a handoff procedure. It inserts a reference to an available tool or Playbook without requiring you to know its internal identifier.
</Tip>

## Human handoff

Open **Build > Escalation** to define when and how the agent hands a conversation to a person. Escalation is off by default.

1. Turn on **Enable escalation**.
2. Describe the situations that should trigger a handoff under **When to escalate**.
3. Optionally add a **Procedure before handoff** to collect context or run an allowed tool or Playbook.

If the procedure is empty, the agent proceeds directly to handoff. Human handoffs arrive in [Botpress Desk](https://desk.support.channel); Viber links to Desk or its onboarding flow when needed.

## Test behavior changes

Open **Preview** after changing Instructions, Playbooks, or escalation. Preview runs the working version, so publishing is not required before this test.

If behavior is inconsistent:

1. Check for conflicting rules across Instructions and the active Playbook.
2. Confirm that referenced tools and Playbooks still exist and are enabled.
3. Start a new Preview conversation to remove earlier conversation context.
4. Use a [flow test](/viber/test-and-improve.md#flow-tests) when the procedure has multiple steps or tool calls.

<Info>Live channels continue to run the published behavior until you publish the working version.</Info>

<LinkCard
  href="/viber/build/knowledge.md"
  title="Add knowledge"
  description="Give the agent reliable information to search when it answers."
  icon="database"
/>

---

# Add knowledge

Source: https://botpress.com/docs/viber/build/knowledge

Give a Viber agent searchable websites, FAQs, files, and web results.

Knowledge gives an agent information it can search when answering a question. It complements [agent behavior](/viber/build/behavior.md): Instructions tell the agent how to behave, while Knowledge supplies facts and reference material.

Tell Vibe what your agent should know, or open **Build > Knowledge** to manage its sources directly.

## Choose a source

| Source | Best for |
| --- | --- |
| **Website** | Product sites, help centers, policy pages, and other maintained web content. |
| **FAQs** | Short, high-intent questions with an approved answer. |
| **Files** | Documents and reference material that you upload to the agent. |
| **Web Search** | Current information outside the agent's managed sources. |

<Frame>
  <Picture alt="Approved shipping and returns FAQs for Acme Support" class="block dark:hidden" src={knowledgeFaqsImg} />
  <Picture alt="Approved shipping and returns FAQs for Acme Support" class="hidden dark:block" src={knowledgeFaqsDarkImg} />
</Frame>

### Website

Add a site or individual pages under **Build > Knowledge > Website**. Viber discovers and prepares the selected pages so the agent can retrieve their content.

Use Website when the content lives online and is best discovered from its URL.

### FAQs

Add a question and its approved answer under **Build > Knowledge > FAQs**. Keep each entry focused on one topic so the agent can retrieve the relevant guidance without mixing unrelated policies.

Use FAQs for important, direct answers such as opening hours, eligibility rules, or a return policy. Use a website or file when the information is longer or needs surrounding context.

### Files

Upload reference documents under **Build > Knowledge > Files**. Uploaded files are stored with the agent in Botpress Cloud and remain available when you open Viber from another computer.

### Web Search

New agents start with Web Search enabled for the entire web. Under **Build > Knowledge > Web Search**, you can:

- keep search open to the entire web;
- limit search to specific sites; or
- turn Web Search off.

Web Search is useful for current or external information. Prefer managed Websites, FAQs, and Files for information that must follow an approved source.

## Wait for content to become ready

Adding a source and preparing it are separate states. A website may need to be discovered and crawled, while a file must upload and index.

Preview displays **Updating Knowledge** while new content is being prepared. New content becomes available as it is ready; opening the Knowledge page does not make an unfinished source immediately searchable.

<Info>
  Preview uses the working knowledge set. Live channels use the published version. Publish again when the new knowledge should be available to customers.
</Info>

## How retrieval works

During a conversation, the agent searches relevant prepared content and can include citations or other source evidence in its answer.

Retrieval is relevance-based. The presence of a source does not guarantee that every passage will be selected for every question. Write clear source content and make sure the agent's Instructions do not prevent it from answering.

## Diagnose a missing answer

If the agent does not use expected knowledge, check the system in this order:

1. **Processing:** Confirm that the website or file finished preparing.
2. **Content:** Open the source and verify that it contains the answer in clear language.
3. **Evidence:** Inspect the answer's citations or retrieval evidence to see what the agent used.
4. **Behavior:** Check for Instructions or a Playbook that conflicts with the source or restricts the topic.
5. **Version:** Confirm whether you tested the working version in Preview or the published version through a live channel.
6. **Conversation:** Start a new Preview conversation and ask the question directly.

<Tip>Use a question test for an important knowledge answer you want to check repeatedly.</Tip>

<LinkCard
  href="/viber/build/tools-and-integrations.md"
  title="Connect tools and integrations"
  description="Give the agent actions it can take in external systems."
  icon="blocks"
/>

---

# Connect tools and integrations

Source: https://botpress.com/docs/viber/build/tools-and-integrations

Connect external services, HTTP APIs, and MCP tools to a Viber agent.

Tools let your agent do more than answer. They can read or update an external system, make an HTTP request, or call a tool exposed by a Model Context Protocol (MCP) server.

Open **Build > Tools** to manage these capabilities.

## Choose the right capability

| Capability | Purpose | Viber location |
| --- | --- | --- |
| **Channel** | Where people talk to the published agent. | Deploy > Channels |
| **Integration** | Actions in another service, such as creating a CRM record. | Build > Tools |
| **HTTP Request** | A custom request to an external HTTP API. | Build > Tools |
| **MCP server** | Tools exposed by a Model Context Protocol server. | Build > Tools |
| **Credential** | A secret that authorizes one of these connections. | The capability's configuration screen or external authorization flow |

Channels and tools serve different purposes. A service available under **Build > Tools** is not automatically available as a deployment channel under **Deploy > Channels**.

Use the live catalog under **Build > Tools** to see the integrations, actions, and setup options currently available.

## Connect an integration

1. Find the service under **Build > Tools**.
2. Add the integration.
3. If Viber displays **Configure**, complete the required authorization or settings.
4. Confirm that the integration is enabled before using one of its actions.

An integration that requires setup is not connected merely because it was added. Zero-configuration integrations can become enabled immediately; other integrations remain in **Needs setup** until configuration succeeds.

Disabling an integration preserves its configuration. Uninstalling it removes the connection and should be treated as a destructive action.

## Tell the agent when to use a tool

A connected integration makes its actions available to the agent, but it does not make the agent call them automatically.

Reference the relevant action in [Instructions or a Playbook](/viber/build/behavior.md#use-tools-in-behavior), then describe when it should be used. A globally referenced action is available without a Playbook. An active Playbook adds its referenced actions to the global actions.

## Test a tool

Test a tool before publishing the agent:

1. Confirm that the integration is enabled and configured.
2. Confirm that the relevant action is referenced in Instructions or a Playbook.
3. Test a representative request in Preview or a flow test.
4. Inspect the tool call, its inputs, and its result.

If the agent does not call the tool, check whether the behavior clearly describes when to use it. If the call fails, inspect the returned error and confirm the tool's authorization and configuration.

## HTTP Request tools

Use an HTTP Request when the agent must call an API that does not fit a catalog integration. Configure the method, URL, parameters, body, headers, and authentication in the HTTP Request editor.

Supported authentication options include no authentication, bearer tokens, basic authentication, and API keys.

## MCP servers

Connect an MCP server when it exposes a set of compatible tools. Configure the server URL and its supported authentication under **Build > Tools**, then enable the individual tools the agent should use.

## Protect credentials

<Warning>
  Never paste API keys, passwords, one-time codes, or other secrets into the Vibe conversation. Enter them only in the relevant configuration or authorization flow.
</Warning>

Complete provider authorization and enter credentials only in the relevant tool configuration. Saved secrets are not read back into the editor. Leave an existing secret field blank when the UI indicates that the saved value should be preserved.

<LinkCard
  href="/viber/test-and-improve.md"
  title="Test and improve"
  description="Verify behavior and tool use before publishing the agent."
  icon="play"
/>

---

# Test and improve

Source: https://botpress.com/docs/viber/test-and-improve

Use Preview, simulations, conversations, and gaps to improve a Viber agent.

Viber provides one improvement loop across manual testing, automated tests, and real conversations:

1. test or observe the agent;
2. inspect the answer, sources, Playbook, and tool activity;
3. correct the agent with Vibe or the structured screens;
4. replay or rerun the scenario; and
5. publish the verified change.

## Preview the working version

Open **Preview** from the main agent navigation to have a conversation with the current working version. Preview can include unpublished Instructions, Playbooks, Knowledge, and tool references.

Use **Start new session** to start a fresh Preview conversation. This clears the conversation context but does not publish or discard the working version.

<Info>
  A hosted Webchat link and other connected channels run the published version. Use Preview when you need to test the working version before it becomes live.
</Info>

## Correct and replay Preview

Flag an incorrect Preview answer to describe what was wrong and send it to Vibe. When the correction changes the working version, Viber can offer **Replay conversation** to rerun the user turns against the updated draft.

Replay is useful when the correction affects an earlier turn or the path through the conversation. Start a new session instead when you want a different scenario.

<Frame>
  <div class="relative aspect-[16/10] w-full overflow-hidden">
    <Picture alt="Flagging an inaccurate Acme Support answer and describing the correction" class="absolute inset-0 h-full w-full object-cover object-[45%_50%] dark:hidden" src={previewFixImg} />
    <Picture alt="Flagging an inaccurate Acme Support answer and describing the correction" class="absolute inset-0 hidden h-full w-full object-cover object-[45%_50%] dark:block" src={previewFixDarkImg} />
  </div>
</Frame>

## Run simulations

Open **Monitor > Simulations** to create repeatable tests. Viber supports question tests and flow tests.

<CardGroup cols={2}>
  <Card title="Question test" icon="circle-help">
    Sends one question, captures one answer and its cited sources, then rates the answer.
  </Card>
  <Card title="Flow test" icon="list-checks">
    Runs a multi-turn scenario against one Playbook and evaluates the resulting behavior.
  </Card>
</CardGroup>

### Question tests

A question test checks an important knowledge answer. The question is the only required content; an optional expected answer can help rate the first run.

Rate the result as:

- **Good** when the answer is ready for the user;
- **Acceptable** when the answer is usable but should improve; or
- **Poor** when the answer is wrong or unsuitable.

The result includes cited sources so you can distinguish missing knowledge from incorrect retrieval, use, tone, or formatting. Later runs can use earlier ratings as a reference, but you can always review and override a rating.

### Flow tests

A flow test exercises one Playbook through a multi-turn conversation with a virtual user. Define:

- the user scenario;
- an optional opening message;
- how external tools should behave; and
- the conditions that determine whether the run passes.

Mock external tool results when a real call would be unsafe, expensive, or inconsistent. Evaluations can check the agent's reply, the full timeline, tool calls and outputs, or Playbook events.

## Diagnose a failed run

A failed simulation does not automatically mean the agent is wrong. Inspect the run before choosing what to change:

1. Read the transcript and the failure rationale.
2. Confirm that a flow test targets the intended Playbook.
3. Check whether mocked or real tool behavior matches the scenario.
4. Check whether the evaluation describes the desired outcome accurately.
5. For question tests, inspect the answer and cited sources.

Use **Fix with Vibe** to send the finished run and its diagnostic context to the builder conversation. After the change, rerun the simulation.

## Learn from real conversations

Open **Monitor > Conversations** to review conversations from Preview and live channels. Use the channel and status context to distinguish a draft test from published traffic.

Open **Monitor > Gaps** to review identified weaknesses and send an actionable correction to Vibe. A gap can originate from feedback, a knowledge rating, or another monitored signal.

<Tip>Publish only after the corrected behavior passes the representative Preview conversation or simulation.</Tip>

<LinkCard
  href="/viber/deploy/channels.md"
  title="Connect channels"
  description="Choose where customers can talk to the published agent."
  icon="radio"
/>

---

# Connect channels

Source: https://botpress.com/docs/viber/deploy/channels

Connect a Viber agent to Webchat, messaging, voice, and SMS channels.

A channel is where people talk to the published agent. Channels are configured under **Deploy > Channels** and are separate from the external actions under Build > Tools.

## Supported channels

| Channel | Purpose |
| --- | --- |
| **Webchat** | Embed the agent on a website or share a hosted chat page. |
| **WhatsApp** | Let customers chat with the agent on WhatsApp. |
| **Telegram** | Connect the agent to Telegram. |
| **Instagram** | Reply to Instagram direct messages. |
| **Messenger** | Connect Facebook Messenger. |
| **Slack** | Use the agent in Slack. |
| **Twilio** | Handle voice and SMS through Twilio. |

<Frame>
  <Picture alt="Webchat configured for Acme Support with additional channels available" class="block dark:hidden" src={channelStatesImg} />
  <Picture alt="Webchat configured for Acme Support with additional channels available" class="hidden dark:block" src={channelStatesDarkImg} />
</Frame>

## Connect a channel

1. Open **Deploy > Channels**.
2. Select **Connect** for the channel you want to use.
3. Choose a supported connection method when the provider offers more than one.
4. Complete the provider authorization or configuration fields.
5. Return to the Channels page and confirm that the connection is ready.

Webchat is enabled for new agents and does not require provider credentials. Other channels require provider-specific setup before they can receive messages.

## Understand channel state

| State | Meaning |
| --- | --- |
| **Enabled** | The channel and its backing integration are enabled, and required configuration is present. |
| **Needs setup** | The channel is enabled, but authorization or required configuration is missing. |
| **Disabled** | The channel is turned off. Existing configuration is preserved. |

Disabling a channel preserves its credentials and configuration so it can be enabled again later.

<Info>
  A channel can be configured before the latest agent behavior is live. Publish the working version whenever the channel should receive new agent changes.
</Info>

## Diagnose a channel that is not replying

Check each layer in order:

1. **Support:** Confirm that the destination is one of the supported channels above.
2. **State:** Confirm that the channel is Enabled, not Needs setup or Disabled.
3. **Provider setup:** Complete every authorization or configuration field requested by the provider.
4. **Published version:** Confirm that the agent was published after the latest changes.
5. **Agent behavior:** Test the same message in Preview. If Preview also fails, diagnose the agent rather than the channel.
6. **Runtime error:** Retry a transient failure. If it persists, record the exact error and contact support.

<Warning>Do not send provider credentials, API keys, passwords, or one-time codes to Vibe or Botpress support.</Warning>

<LinkCard
  href="/viber/deploy/publish-and-share.md"
  title="Publish and share"
  description="Make the working version live and share or embed Webchat."
  icon="send"
/>

---

# Publish and share

Source: https://botpress.com/docs/viber/deploy/publish-and-share

Publish a Viber agent and share or embed its Webchat.

Publishing promotes the current working version to the version used by live channels. It does not create a separate agent.

## Working and published state

| Surface | Version it runs |
| --- | --- |
| **Preview** | The current working version, including unpublished changes. |
| **Hosted Webchat** | The published version. |
| **Connected channels** | The published version. |

After an agent is published, later edits remain in the working version until you publish again.

## Publish changes

1. Select **Publish changes**.
2. Review the enabled channels and change summary.
3. Inspect the detailed channel or change list when needed.
4. Publish the working version.

The only user-facing publish prerequisite is at least one enabled channel. New agents start with Webchat enabled.

Readiness guidance is advisory and does not block publishing.

<Info>Publish again whenever live channels should receive changes made after the previous publish.</Info>

## Share the hosted Webchat

Open **Deploy > Channels > Webchat**, then select **Share your agent**. Copy the **Shareable link** to give someone access to the published agent in a browser.

## Embed Webchat on a website

In **Share your agent**, copy the provided embed snippet and paste it immediately before the closing `</body>` tag on your site.

The snippet contains the correct Webchat loader and the agent's current configuration file. Copy it from Viber rather than writing it by hand.

<Frame>
  <div class="relative aspect-[16/10] w-full overflow-hidden">
    <Picture alt="The Acme Support Webchat embed snippet and website preview" class="absolute inset-0 h-full w-full object-cover object-[44%_50%] dark:hidden" src={webchatEmbedImg} />
    <Picture alt="The Acme Support Webchat embed snippet and website preview" class="absolute inset-0 hidden h-full w-full object-cover object-[44%_50%] dark:block" src={webchatEmbedDarkImg} />
  </div>
</Frame>

### Choose a deployment mode

Under the Webchat deployment settings, choose one of these interfaces:

| Mode | Behavior |
| --- | --- |
| **Toggle** | Opens from the default chat bubble or a custom launcher element. |
| **Embedded** | Renders inside a page element. The default element ID is `bp-embedded-webchat`. |

Toggle can use the standard chat bubble, a custom launcher element, and an optional launcher image. Embedded mode uses the configured container element ID.

## Webchat controls and plans

Some Webchat controls depend on your workspace plan. Viber identifies plan requirements in the Webchat editor.

## Diagnose a publishing problem

If **Publish changes** is disabled, open **Deploy > Channels** and enable at least one channel.

If a publish request fails even though a channel is enabled:

1. Keep the exact error message.
2. Confirm that the channel is still enabled and configured.
3. Retry the publish once.
4. Contact support if the error persists.

<Warning>Never include provider credentials or access tokens in a support message.</Warning>

<Tip>
  When Preview works but the hosted Webchat behaves differently, confirm that the latest working changes were published before diagnosing the channel.
</Tip>

---

# 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](/integrations/get-started/botpress-hub.md), which includes integrations built by both Botpress and by users.

<Note>
  Want to build your own integration and publish it on [Botpress Hub](/integrations/get-started/botpress-hub.md)? Check out
  our [integrations SDK](/integrations/sdk/integration/getting-started.md).
</Note>

## Get Started

<Card title="Botpress Hub" icon="boxes" href="/integrations/get-started/botpress-hub.md">
  Marketplace to find and install integrations
</Card>

## Popular integrations

<CardGroup cols={3}>
  <Card title="WhatsApp" icon="simple-icons:whatsapp" href="/integrations/integration-guides/whatsapp/introduction.md">
    Integrate your bot with WhatsApp
  </Card>
  <Card title="Telegram" icon="simple-icons:telegram" href="/integrations/integration-guides/telegram.md">
    Integrate your bot with Telegram
  </Card>
  <Card title="Messenger" icon="simple-icons:messenger" href="/integrations/integration-guides/messenger.md">
    Integrate your bot with Messenger
  </Card>
</CardGroup>

---

# 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](/integrations/sdk/overview.md) section.
</Note>

## Access Botpress Hub

To access Botpress Hub, select <Icon icon="boxes"/> **Explore Hub** in the upper-right corner of the [Studio](/studio/introduction.md).

## Install an integration

Use the search bar or filters to find an integration:

![Search Botpress Hub](./assets/hub-search.png)

Then, select **Install Integration** to install it to your bot:

![Install integration](./assets/install-integration.png)

## Configure your integration

After installing an integration, you usually need to configure it before you can start using it:

![Configure an integration](./assets/configure-integration.png)

The exact configuration steps will vary depending on which integration you're trying to setup.

---

# 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](/studio/concepts/knowledge-base/add-sources.md#websites) provides.

## Setup

<Info>
  You will need:

- A [published bot](/studio/get-started/quick-start.md)
- 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](https://botpress.com/docs/studio/concepts/cards)** available with the integration:
<IntegrationCards/>

## Triggers

Here’s a reference for all **[Triggers](https://botpress.com/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>
<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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](https://botpress.com/docs/studio/concepts/cards/introduction)** available with the integration:

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

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

## Triggers

<IntegrationEvents/>

---

# 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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/introduction.md">
  Check out the Chat API documentation for more information
</Card>

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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>

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
</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](/studio/concepts/workflows.md) 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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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
        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 or 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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.
    2. 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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
      {
        "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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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
      {
        "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>

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/manage-your-agent/human-handoff.md).
</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>
      <Picture alt="Start HITL Card" class="block dark:hidden" src={startHitlCardImg}/>
      <Picture alt="Start HITL Card" class="hidden dark:block" src={startHitlCardDarkImg}/>
    </Frame>

  </Step>
  <Step>
    In the Card's [inspector](/studio/concepts/cards/introduction.md#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](/studio/get-started/manage-your-agent/human-handoff.md) guide.

</Check>

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/integrations/integration-guides/hitl/introduction.md) 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)](/integrations/integration-guides/hitl/introduction.md). 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](/studio/concepts/cards/send-messages.md#text), [sent to an external system](/studio/concepts/cards/execute-code.md), or [saved to a Botpress table](/studio/concepts/cards/tables.md#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](/integrations/integration-guides/hitl/introduction.md#step-3-add-the-start-hitl-card-to-your-workflow) Card, insert an [Execute Code](/studio/concepts/cards/execute-code.md) Card that records when the user was handed off to HITL. Use the following code:

```js
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](/integrations/integration-guides/hitl/introduction.md#step-3-add-the-start-hitl-card-to-your-workflow) Card, insert another [Execute Code](/studio/concepts/cards/execute-code.md) Card that computes the time until an agent was assigned and formats the result. Use the following code:

```js
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](/studio/concepts/cards/send-messages.md#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](/studio/concepts/cards/tables.md#update-record) or [Insert Table Row](/studio/concepts/cards/tables.md#insert-record) Card to persist the data for reporting.
- **Send it to an external system**: Use an [Execute Code](/studio/concepts/cards/execute-code.md) 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](/studio/get-started/quick-start.md)
  - 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](/studio/concepts/cards/introduction.md) and [Triggers](/studio/concepts/triggers.md) to interact with your HubSpot account.
</Check>

---

## Cards

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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.
{/* TODO update description */}

## Setup

<Info>
  You will need:

- A [published bot](/studio/get-started/quick-start.md)
- 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**.
    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 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# Improvement

Source: https://botpress.com/docs/integrations/integration-guides/improvement

<OpenInHub />
The official Improvement integration lets you provide feedback on your bot's responses in the [emulator](/studio/concepts/emulator.md). 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](/studio/get-started/quick-start.md)
</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>
      <Picture alt="Improve response" class="block dark:hidden" src={improveResponseImg}/>
      <Picture alt="Improve response" class="hidden dark:block" src={improveResponseDarkImg}/>
    </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>
      <Picture alt="Feedback" class="block dark:hidden" src={feedbackImg}/>
      <Picture alt="Feedback" class="hidden dark:block" src={feedbackDarkImg}/>
    </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](/studio/concepts/tables.md) as a row:

<Frame>
  <Picture alt="Feedback" class="block dark:hidden" src={feedbackTableImg} />
  <Picture alt="Feedback" class="hidden dark:block" src={feedbackTableDarkImg} />
</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.

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
            - 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](/studio/get-started/quick-start.md)
            - 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 titleSize="h3">
            <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.
                2. 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](/integrations/integration-guides/instagram.md#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](/studio/get-started/quick-start.md)
            - 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# Intercom

Source: https://botpress.com/docs/integrations/integration-guides/intercom

<OpenInHub />

<Picture src={intercomImg} alt="" />

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

<Picture src={intercomUrlImg} alt="" />

### 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
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
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 }
)
```

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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](/studio/concepts/nodes/autonomous-node.md), 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>

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
</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>
  <Picture alt="Auto-optimize" class="block dark:hidden" src={autoOptimizeImg} />
  <Picture alt="Auto-optimize" class="hidden dark:block" src={autoOptimizeDarkImg} />
</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.

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# Line

Source: https://botpress.com/docs/integrations/integration-guides/line

<OpenInHub />

<Picture src={lineImg} alt="" />

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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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 tracking and react to repository file events.

## Setup

<Tabs>
  <Tab title="Basic configuration">
    <Info>
      You will need:

      - A [published bot](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

## Troubleshooting

If you run into errors when using the integration's Cards, check out your bot's [Logs](/studio/concepts/debugger-logs-json.md#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

import AiIcon from '@/components/AiIcon.astro'
import Accordion from '@/components/Accordion.astro'
import IntegrationCards from '@/components/integrations/IntegrationCards.astro'
import IntegrationEvents from '@/components/integrations/IntegrationEvents.astro'
import OpenInHub from '@/components/integrations/OpenInHub.astro'

<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](/studio/get-started/quick-start.md)
    - 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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](/api-reference/files-api/getting-started.md). 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](/studio/concepts/workflows.md#main).
  </Step>
  <Step>
    [Add a new Node](/studio/concepts/nodes/introduction.md#add-a-node) to the Workflow.
  </Step>
  <Step>
    Rename the Node to `Router`, then move it between the [Start Node](/studio/concepts/nodes/introduction.md) and any other existing Nodes:

    <Frame>
      <Picture alt="Reply to comments in DMs 1" class="block dark:hidden" src={messengerReplyInDm1Img}/>
      <Picture alt="Reply to comments in DMs 1" class="hidden dark:block" src={messengerReplyInDm1DarkImg}/>
    </Frame>

  </Step>
  <Step>
    Add two [Expression Cards](/studio/concepts/cards/flow-logic.md#expression) to the `Router` Node.
  </Step>
  <Step>
    Open the second Expression Card's [inspector](/studio/concepts/cards/introduction.md#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](/studio/concepts/cards/introduction.md#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>
      <Picture alt="Reply to comments in DMs 2" class="block dark:hidden" src={messengerReplyInDm2Img}/>
      <Picture alt="Reply to comments in DMs 2" class="hidden dark:block" src={messengerReplyInDm2DarkImg}/>
    </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](/studio/concepts/cards/send-messages.md#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>
      <Picture alt="Reply to comments in DMs 3" class="block dark:hidden" src={messengerReplyInDm3Img}/>
      <Picture alt="Reply to comments in DMs 3" class="hidden dark:block" src={messengerReplyInDm3DarkImg}/>
    </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](/studio/concepts/nodes/introduction.md#end):

    <Frame>
      <Picture alt="Reply to comments in DMs 4" class="block dark:hidden" src={messengerReplyInDm4Img}/>
      <Picture alt="Reply to comments in DMs 4" class="hidden dark:block" src={messengerReplyInDm4DarkImg}/>
    </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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

## Tags

You can read [event tags](/studio/guides/advanced/event-properties.md#param-tags) to get information about an active Messenger conversation:

### Message ID

To get the Messenger ID of a message:

```js
event.tags.message['messenger:id']
```

### Recipient ID

To get the Messenger ID of the recipient:

```js
event.tags.message['messenger:recipientId']
```

### Sender ID

To get the Messenger ID of the sender:

```js
event.tags.message['messenger:senderId']
```

### Conversation ID

To get the Messenger ID of the conversation:

```js
event.tags.conversation['messenger:id']
```

### User ID

To get the Messenger ID of the user:

```js
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](/studio/get-started/quick-start.md)
- 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.
    2. 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/manage-your-agent/inspect.md#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

<IntegrationCards/>

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

---

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

## Troubleshooting

If you run into errors when using the integration's Cards, check out your bot's [Logs](/studio/concepts/debugger-logs-json.md#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>

---

# 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](/studio/get-started/quick-start.md)
      - 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](/studio/get-started/quick-start.md)
      - A [Slack workspace](https://slack.com/get-started?entry_point=help_center#/createnew)
    </Info>

      {/* ### Step 1: Install the Slack integration in Botpress */}

      <Steps titleSize="h3">
        <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 2: Create a Slack app */}

        <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 title="JSON"

{
"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 title="YAML"
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 3: Install the app to your workspace */}

        <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 4: Configure the integration in Botpress */}

        <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 5: Add the integration's webhook URL */}

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

{/* TODO: test and revise steps below */}
{/* <Note>
Enabling reply threading alone doesn't stop your bot from posting in the main channel. To restrict responses exclusively to threads, modify your Workflow to terminate when receiving messages from the main channel:

1. Insert a Standard Node at the very beginning of your Main Workflow. Then, connect it to your existing Workflow.
2. Add an [expression Card](/studio/concepts/cards/flow-logic.md#expression) to the Standard Node.
3. Set the expression Card's condition to `event.channel === 'channel'`.
   TODO: modify conditional to account for other channel types
4. Create an End Card and connect the expression Card to it.
   </Note> */}

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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

## Tags

You can read [event tags](/studio/guides/advanced/event-properties.md#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 />

<Picture src={sunshineConversationsImg} alt="" />

## Prerequisites

- A [Smooch app](https://app.smooch.io) with a channel configured
- A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/studio/get-started/quick-start.md)

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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# Zendesk Messaging

Source: https://botpress.com/docs/integrations/integration-guides/sunshine-conversations/zendesk-messaging

import OpenInHub from '@/components/integrations/OpenInHub.astro'

<OpenInHub />

<Picture src={sunshineConversationZendeskImg} alt="" />

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](/studio/get-started/quick-start.md)

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

<Picture src={sunshineConversationConfigImg} alt="" />

## Setup in Zendesk

### Configure the Webhook

1. Open your Zendesk Admin Center.

<Picture src={zendeskAdminCenterImg} alt="" />

2. Click on **Apps and Integrations** and **Conversations Integrations**

<Picture src={zendeskIntegrationsImg} alt="" />

3. Give any name and put the **webhook URL** that you copied from Botpress.

<Picture src={zendeskWebhooksImg} alt="" />

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

<Picture src={zendeskSecretImg} alt="" />

<br />

<Picture src={sunshineConversationIntegrationConfigImg} alt="" />

### Configure the API Credentials

1. Click on **Apps and Integrations** view and **Conversation API**

<Picture src={zendeskConversationsApiImg} alt="" />

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.

<Picture src={sunshineConversationIntegrationConfig2Img} alt="" />

<br />

<Picture src={sunshineConversationSharedSecretsImg} alt="" />

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

---

# Telegram

Source: https://botpress.com/docs/integrations/integration-guides/telegram

Add your bot to Telegram using the official integration.

import YouTube from '@/components/YouTube.astro'
import IntegrationCards from '@/components/integrations/IntegrationCards.astro'
import IntegrationEvents from '@/components/integrations/IntegrationEvents.astro'
import OpenInHub from '@/components/integrations/OpenInHub.astro'

<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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

## Tags

You can read [event tags](/studio/guides/advanced/event-properties.md#param-tags) to get information about an active Telegram conversation:

### Telegram conversation ID

To get the Telegram conversation ID:

```js
{
  {
    event.tags.conversation['telegram:id']
  }
}
```

### Telegram user ID

To get the Telegram user ID:

```js
{
  {
    event.tags.user['telegram:id']
  }
}
```

### Telegram message ID

To get the Telegram message ID:

```js
{
  {
    event.tags.message['telegram:id']
  }
}
```

---

# Trello

Source: https://botpress.com/docs/integrations/integration-guides/trello

<OpenInHub />

<Picture src={trelloImg} alt="" />

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](/studio/get-started/quick-start.md)

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

<Picture src={trelloApikeyImg} alt="" />

3. Click on the "Token" link (marked in the image below) and authorize the Power-Up access to your Trello account by selecting **Allow**.

<Picture src={trelloTokenImg} alt="" />

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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# Twilio

Source: https://botpress.com/docs/integrations/integration-guides/twilio

<OpenInHub />

<Picture src={twilioImg} alt="" />

<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](/studio/get-started/quick-start.md)

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

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# Viber

Source: https://botpress.com/docs/integrations/integration-guides/viber

<OpenInHub />

<Picture src={viberImg} alt="" />

## Prerequisites

- A [Viber account](https://www.viber.com/)
- A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/studio/get-started/quick-start.md)

## 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!

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# Vonage

Source: https://botpress.com/docs/integrations/integration-guides/vonage

<OpenInHub />

<Picture src={vonageImg} alt="" />

## 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](/studio/get-started/quick-start.md)

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

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
</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 title="JavaScript"
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 title="cURL"
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 title="Python"
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 title="PHP"
<?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 title="Go"
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 title="Java"
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 title="Ruby"
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](/studio/concepts/triggers.md#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](/studio/guides/advanced/event-properties.md) 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
      "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
      "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](/studio/concepts/variables/overview.md).

### Payload size limit

The maximum size for a Webhook payload is 100 MB.

---

## Cards

<IntegrationCards/>

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- 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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

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

<IntegrationCards/>
---

## Triggers

<IntegrationEvents/>
---

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

{/* vale Vale.Spelling = NO */}
| Title in Botpress | WhatsApp Button | WhatsApp Dropdown |
| :---------------------------- | :----------------------- | :------------------------- |
| "This is a title in Botpress" | "This is a title in ..." | "This is a title in Botp..." |
{/* vale Vale.Spelling = YES */}

---

## 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](/studio/concepts/cards/send-messages.md#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](/studio/concepts/cards/execute-code.md) 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" required>
    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" required>
    The URL of the image file
  </ResponseField>
</Accordion>

<Accordion title="Audio">
  <ResponseField name="audioUrl" type="string" required>
    The URL of the audio file
  </ResponseField>
</Accordion>

<Accordion title="Video">
  <ResponseField name="videoUrl" type="string" required>
    The URL of the video file
  </ResponseField>
</Accordion>

<Accordion title="File">
  <ResponseField name="fileUrl" type="string" required>
    The URL of the file
  </ResponseField>
  <ResponseField name="filename" type="string" required>
    The name of the file
  </ResponseField>
</Accordion>

<Accordion title="Location">
  <ResponseField name="latitude" type="number" required>
    The latitude coordinate of the location
  </ResponseField>
  <ResponseField name="longitude" type="number" required>
    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](/api-reference/files-api/getting-started.md). 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 titleSize="h3">
  <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
    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 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 titleSize="h3">
  <Step title="Add the Start Conversation Card">
    In Studio, add a **Start Conversation** Card to any Node:

    ![Start Conversation](./assets/start-conversation.png)

  </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
      ["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:

![Output Value field](./assets/output-value.png)

The output value of this action will be an object with the following structure:

```js
{
  conversationId: 'xxxxxxxxxxxxxxxxxxxxx'
}
```

## Create the conversation from code

You can also call `actions.whatsapp.startConversation` in an [Execute Code](/studio/concepts/cards/execute-code.md) Card to start a conversation:

```ts
actions.whatsapp.startConversation({
  conversation: {
    userPhone: '+1 123 456 7890',
    templateName: 'test_message',
    templateLanguage: 'en',
    templateVariablesJson: JSON.stringify(['First value', 'Second value']),
  },
})
```

---

# 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 titleSize="h3">
  <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/`).

    ![Webhook Configuration page with webhook URL](./assets/copy-webhook-url.png)

  </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](/integrations/integration-guides/webhook.md#send-data-to-your-webhook).
</Note>

## 2. Add the webhook trigger and Start Conversation in Studio

<Steps titleSize="h3">
  <Step title="Add the Event trigger">
    Open the [Workflow](/studio/concepts/workflows.md) where you want to handle the webhook. Right-click on the canvas and select **Trigger**, then choose the **Event** trigger from the Webhook integration.

    ![Add Event trigger from Webhook](./assets/add-event-trigger.png)

  </Step>
  <Step title="Add the Start Conversation Card">
    Add a Node after the trigger and add the **Start Conversation** Card to it.

    ![Add Start Conversation Card to node](./assets/add-start-convo-card-with-webhook.png)

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

    ![Start Conversation Card with User Phone, Template name, Template language, and Template variables](./assets/start-conversation-with-webhook.png)

  </Step>
  <Step title="Store the WhatsApp conversation ID">
    In the Start Conversation Card, set **Store result in** to a [Workflow variable](/studio/concepts/variables/scopes/workflow.md) (for example, `whatsAppOutput`). This variable will hold the new conversation's ID.

    ![Store output value in workflow variable](./assets/store-whatsapp-output.png)

  </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](/studio/concepts/nodes/autonomous-node.md) or your main bot Workflow) run in the same WhatsApp conversation, set `event.conversationId` to the ID returned by the Start Conversation Card.

<Steps titleSize="h3">
  <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.

    ![Add Execute Code Card](./assets/add-execute-code-card-with-webhook.png)

  </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
    event.conversationId = workflow.whatsAppOutput.conversationId
    ```

    ![Store result in workflow variable](./assets/assign-convo-id.png)

    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](/studio/concepts/nodes/autonomous-node.md) 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.

![Workflow with start connection to main Workflow](./assets/autonomous-node-with-start.png)

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](/studio/concepts/nodes/autonomous-node.md) 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>

---

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

<Picture src={zapierImg} alt="" />

## 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](/studio/get-started/quick-start.md)

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

{/* vale Botpress.workflows = NO */}

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

{/* vale Botpress.workflows = YES */}

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:

<Picture src={zapierCardsImg} alt="" />

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:

<Picture src={zapierEventsImg} alt="" />

4. Then add an Execute Code card with the following code assuming you sent your data in JSON format:

```js
workflow.zapierData = JSON.parse(event.payload.body)
```

{/* vale Botpress.workflows = NO */}

5. Now the rest of your trigger workflow can use the `{{ workflow.zapierData }}` variable to access the data you sent from Zapier.

{/* vale Botpress.workflows = YES */}

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

<Picture src={zapierTriggerImg} alt="" />

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.

<Picture src={zapierWorkflowImg} alt="" />

---

## Cards

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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](/studio/get-started/quick-start.md)
- A [Zendesk account](https://www.zendesk.com/sign-up/)
</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

<IntegrationCards/>

---

## Triggers

<IntegrationEvents/>

---

# 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" horizontal icon="play" href="/integrations/sdk/integration/getting-started.md">
  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 Cols={2}>
  <Card title="Read more" horizontal icon="book" href="/integrations/sdk/interface/introduction.md">
    Learn more about interfaces
  </Card>
  <Card title="How-to" horizontal icon="graduation-cap" href="/integrations/sdk/interface/how-tos/implementing-hitl.md">
    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" horizontal icon="play" href="/integrations/sdk/bots-as-code.md">
  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 Cols={2}>
  <Card title="Read more" horizontal icon="book" href="/integrations/sdk/interface/how-tos/implementing-hitl.md">
    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.

---

# 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 title="npm"
npm install -g @botpress/cli
```

```bash title="pnpm"
pnpm install -g @botpress/cli
```

```bash title="yarn"
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
bp --help
```

---

# 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](/integrations/get-started/introduction.md).
</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 title="npm"
npm install -g @botpress/cli
```

```bash title="pnpm"
pnpm install -g @botpress/cli
```

```bash title="yarn"
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
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
bp login
```

{/* TODO: add a guide on how to create a personal access token and link to it. */}

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

{/* TODO: add a guide on how to claim a Workspace handle and link to it. */}

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

{/* TODO: add a guide on how to install an integration in the studio and link to it. */}

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

{/* TODO(driftable): This script is subject to changes and should be autogenerated */}

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

{/* TODO(driftable): This script is subject to changes and should be autogenerated */}

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

---

# 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
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>
    <Picture alt="Configuration schema" class="block dark:hidden" src={configLinearImg}/>
    <Picture alt="Configuration schema" class="hidden dark:block" src={configLinearDarkImg}/>
  </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]
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>
      <Picture alt="First schema" class="block dark:hidden" src={configGithub1Img}/>
      <Picture alt="First schema" class="hidden dark:block" src={configGithub1DarkImg}/>
    </Frame>
  </Tab>
  <Tab title="Second schema">
    <Frame>
      <Picture alt="Second schema" class="block dark:hidden" src={configGithub2Img}/>
      <Picture alt="Second schema" class="hidden dark:block" src={configGithub2DarkImg}/>
    </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.

---

# 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**:
    <Picture src={makePublicImg} alt="" />
    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.

<Picture src={botpressProfileImg} alt="" />

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

<Picture src={requestVerificationImg} alt="" />

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.

---

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

{/* vale Botpress.workflows = NO */}
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.
{/* vale Vale.Spelling = YES */}

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.

---

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

---

# 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

---

# 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
    {
      "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
    {
      "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`](/integrations/sdk/cli-reference.md#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
    {
      "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
    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
  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 Cols={2}>
  <Card
    horizontal
    title="Human in the loop"
    href="/integrations/sdk/interface/how-tos/implementing-hitl.md"
  >
    How to implement Human in the loop
  </Card>
</CardGroup>

---

# Implementing Human in the loop (HITL) in an integration

Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/implementing-hitl

<p>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 term="integration" id="integration">
    The code that connects Botpress to an external service.
  </Definition>
  <Definition term="external service" id="external-service">
    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 term="human agent" id="human-agent">
    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 term="end user" id="end-user">
    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 term="external user" id="external-user">
    A representation of an end user within the external service. This is typically created when a HITL session is started.
  </Definition>
  <Definition term="HITL session" id="hitl-session">
    A conversation between an end user and a human agent. This is typically represented as a _ticket_ in the external service.
  </Definition>
  <Definition term="HITL interface" id="hitl-interface">
    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 term="HITL plugin" id="hitl-plugin">
    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 term="entity" id="entity">
    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 id="external-service"/> providing HITL functionality **must** support the following:

- An API that allows creating <DefinitionReference id="external-user" plural/>.
- An API that allows creating <DefinitionReference id="hitl-session" plural/>.
- An API that allows adding messages to <DefinitionReference id="hitl-session" plural/>.
- An API that allows closing <DefinitionReference id="hitl-session" plural/>.
- Webhooks that can notify your <DefinitionReference id="integration"/> of the following events:
  - <DefinitionReference id="hitl-session" capitalize/> closure.
  - <DefinitionReference id="human-agent" capitalize/> assignment.
  - <DefinitionReference id="human-agent" capitalize/> reply.

## Updating your `package.json` file

### Finding the current interface version

The current version of the `hitl` interface is: <code>2.0.0</code>

You will need this version number for the next steps.

### Adding the interface as a dependency

Once you have the <DefinitionReference id="hitl-interface"/> version, you can add it as a dependency to your <DefinitionReference id="integration"/>:

<Steps>
  <Step title="Open the package.json file">
    Open your <DefinitionReference id="integration"/>'s `package.json` file.
  </Step>
  <Step title="Add the dependencies section">
    If there is no `bpDependencies` section in your <DefinitionReference id="integration"/>'s `package.json` file, create one:

    ```json package.json {2}
    {
      "bpDependencies": {}
    }
    ```

  </Step>
  <Step title="Add the interface as a dependency">
    In the `bpDependencies` section, add the <DefinitionReference id="hitl-interface"/> as a dependency. For example, for version `2.0.0`, you would add the following:

    ```json package.json {3}
    {
      "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 id="hitl-interface"/> as a dependency, you can run the [`bp add`](/integrations/sdk/cli-reference.md#add) command to install it. This command will:
  - Download the interface from Botpress.
  - Install it in a directory named `bp_modules` in your <DefinitionReference id="integration"/>'s root directory.
  </Step>
</Steps>

### Adding a helper build script

To keep your <DefinitionReference id="integration"/> 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 id="integration"/>'s `package.json` file.
  </Step>
  <Step title="Add the build script">
    In the `scripts` section, add the following script:
    ```json package.json {3}
    {
      "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 id="hitl-interface" /> and build your <DefinitionReference id="integration" />.

## Editing your integration definition file

### Adding the interface to your integration definition file

Now that the <DefinitionReference id="hitl-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 <DefinitionReference id="integration"/>'s `integration.definition.ts` file.
  </Step>
  <Step title="Import the interface">
    At the top of the file, import the <DefinitionReference id="hitl-interface"/>:
    ```typescript integration.definition.ts
    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}
    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 id="external-service"/>. For example, if the <DefinitionReference id="external-service"/> uses the term "ticket" to refer to a <DefinitionReference id="hitl-session"/>, 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}
    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 id="external-service"/>. This will help you avoid confusion and make your <DefinitionReference id="integration"/> easier to
  understand.
</Tip>

#### Renaming actions

The `hitl` interface defines three actions that are used to interact with the <DefinitionReference id="external-service"/>:

- `createUser` - Used by the <DefinitionReference id="hitl-plugin"/> to request the creation of a user in the <DefinitionReference id="external-service"/> and on Botpress.
- `startHitl` - Used by the <DefinitionReference id="hitl-plugin"/> to request the creation of a <DefinitionReference id="hitl-session"/> in the <DefinitionReference id="external-service"/>.
- `stopHitl` - Used by the <DefinitionReference id="hitl-plugin"/> to request the closure of a <DefinitionReference id="hitl-session"/> in the <DefinitionReference id="external-service"/>.

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}
.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 id="integration"/> 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 id="integration"/> to notify the <DefinitionReference id="hitl-plugin"/> that a <DefinitionReference id="human-agent"/> has been assigned to a <DefinitionReference id="hitl-session"/>.
- `hitlStopped` - Emitted by your <DefinitionReference id="integration"/> to notify the <DefinitionReference id="hitl-plugin"/> that a <DefinitionReference id="hitl-session"/> 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}
.extend(hitl, () => ({
  events: {
    hitlAssigned: {
      name: 'agentAssigned',
    },
  },
}))
```

#### Renaming channels

The `hitl` interface defines these channels:

- `hitl` - Used by the <DefinitionReference id="hitl-plugin"/> to send and receive messages from the <DefinitionReference id="external-service"/>. This represents the communication channel for the <DefinitionReference id="hitl-session"/>, 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}
.extend(hitl, () => ({
  channels: {
    hitl: {
      name: 'supportTicket',
    },
  },
}))
```

## Implementing the interface

### Implementing the actions

#### Implementing `createUser`

The `createUser` action is used by the <DefinitionReference id="hitl-plugin"/> to request the creation of an <DefinitionReference id="external-user"/> (a _requester_) in the <DefinitionReference id="external-service"/>.

<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 id="external-user"/> on the <DefinitionReference id="external-service"/> using the <DefinitionReference id="external-service"/>'s API or SDK.
  </Step>
  <Step title="Map the external user to the Botpress user">
    Update the <DefinitionReference id="external-user"/> on the <DefinitionReference id="external-service"/> to map it to the Botpress user. Please refer to the <DefinitionReference id="external-service"/>'s documentation to know how to set extra metadata for the <DefinitionReference id="external-user"/>. The <DefinitionReference id="integration"/> must be able at any time to query the <DefinitionReference id="external-service"/> in order to retrieve the Botpress user ID from the <DefinitionReference id="external-user"/>.
  </Step>
  <Step title="Map the Botpress user to the external user">
    Update the Botpress user to map it to the <DefinitionReference id="external-user"/>. This is typically done by setting a tag on the Botpress
    user with the <DefinitionReference id="external-user"/>'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}
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 id="hitl-plugin"/> to request the creation of a <DefinitionReference id="hitl-session"/> (typically a _ticket_) in the <DefinitionReference id="external-service"/>.

<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 id="external-user"/>'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 id="external-service"/>, create the <DefinitionReference id="hitl-session"/>. This is typically represented as a _ticket_ in the <DefinitionReference id="external-service"/>.

  </Step>
  <Step title="Map the Botpress conversation to the HITL session">
    Update the Botpress conversation to map it to the <DefinitionReference id="hitl-session"/>. 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 id="hitl-session"/> on the <DefinitionReference id="external-service"/> to map it to the Botpress conversation. Please refer to the <DefinitionReference id="external-service"/>'s documentation to know how to set extra metadata for the <DefinitionReference id="hitl-session"/> (typically a _ticket_). The <DefinitionReference id="integration"/> must be able at any time to query the <DefinitionReference id="external-service"/> in order to retrieve the Botpress conversation ID from the <DefinitionReference id="hitl-session"/>.

  </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}
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 id="external-service"/> to provide the <DefinitionReference id="human-agent"/> with context about the conversation. This parameter is an array of every message that was sent in the conversation prior to the <DefinitionReference id="hitl-session"/> being started.

<Expandable title="TypeScript schema for the messageHistory parameter">

```typescript
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 id="external-service"/>, you can do so by iterating over the `messageHistory` array and sending each message to the <DefinitionReference id="external-service"/> using its API or SDK. However, doing so might cause a significant number of notifications being sent to the <DefinitionReference id="external-service"/>. 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
## 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 id="external-service"/> requires extra parameters when starting a <DefinitionReference id="hitl-session"/>, 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 id="external-service"/> requires a `priority` parameter, you can add it like this:

```typescript integration.definition.ts {5}
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}
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 id="hitl-plugin"/> to request the closure of a <DefinitionReference id="hitl-session"/> (typically a _ticket_) in the <DefinitionReference id="external-service"/>.

<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 id="hitl-session"/>'s ID.
  </Step>
  <Step title="Close the HITL session">

    On the <DefinitionReference id="external-service"/>, close the <DefinitionReference id="hitl-session"/>. This is typically involves _resolving_ or _closing_ a _ticket_ in the <DefinitionReference id="external-service"/>.

  </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 id="hitl-interface"/>.
</Note>

As reference, here's how this logic is implemented in the Zendesk integration:

```typescript src/index.ts {4,9,17,22}
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 id="hitl-plugin"/> relay <DefinitionReference id="end-user"/> messages to the <DefinitionReference id="hitl-session"/>, which is usually a _ticket_ or _thread_ in the <DefinitionReference id="external-service"/>.

<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 id="hitl-session"/>'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 id="end-user"/>. Retrieve the <DefinitionReference id="external-user"/>'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 id="external-user"/>'s ID from the tags of the attached Botpress user.
  </Step>
  <Step title="Send the message to the HITL session">

    Using the <DefinitionReference id="external-service"/>'s API or SDK, send the message to the <DefinitionReference id="hitl-session"/>. 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}
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 id="integration"/> receives notifications about these events:

- A new message is added to the <DefinitionReference id="hitl-session"/> (usually a _ticket_).
- A <DefinitionReference id="human-agent"/> has been assigned to the <DefinitionReference id="hitl-session"/>.
- The <DefinitionReference id="hitl-session"/> was closed.

#### Incoming messages

When notified by the <DefinitionReference id="external-service"/> that a new message has been added to the <DefinitionReference id="hitl-session"/>, 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 id="hitl-session"/>'s metadata.
  </Step>
  <Step title="Retrieve the external user's ID">Retrieve the <DefinitionReference id="external-user"/>'s ID from the <DefinitionReference id="hitl-session"/>'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 id="external-service"/> that a <DefinitionReference id="human-agent"/> has been assigned to the <DefinitionReference id="hitl-session"/>, you should notify the <DefinitionReference id="hitl-plugin"/> by emitting the `hitlAssigned` event:

<Steps>
  <Step title="Retrieve the Botpress conversation's ID">
    Retrieve the Botpress conversation's ID from the <DefinitionReference id="hitl-session"/>'s metadata.
  </Step>
  <Step title="Retrieve the external user's ID">Retrieve the <DefinitionReference id="external-user"/>'s ID from the <DefinitionReference id="hitl-session"/>'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 id="external-service"/> that the <DefinitionReference id="hitl-session"/> was closed, you should notify the <DefinitionReference id="hitl-plugin"/> by emitting the `hitlStopped` event:

<Steps>
  <Step title="Retrieve the Botpress conversation's ID">
    Retrieve the Botpress conversation's ID from the <DefinitionReference id="hitl-session"/>'s metadata.
  </Step>
  <Step title="Retrieve the external user's ID">Retrieve the <DefinitionReference id="external-user"/>'s ID from the <DefinitionReference id="hitl-session"/>'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>

---

# Implementing unidirectional file synchronization in an integration

Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/implementing-file-sync

<div class="flex items-center gap-4 not-prose mb-6">
  <div class="shrink-0 size-16 rounded-xl bg-purple-700 flex items-center justify-center text-white">
    <Icon icon="file-input" class="size-8!" />
  </div>
  <p class="m-0 text-foreground">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>
</div>

## 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 term="integration" id="integration">
    The code that connects Botpress to an external service.
  </Definition>
  <Definition term="external service" id="external-service">
    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 term="file synchronization interface" id="files-readonly">
    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 term="file synchronizer plugin" id="file-synchronizer">
    The Botpress plugin that orchestrates file synchronization. This plugin is responsible for managing the synchronization process, including scheduling, error handling, and reporting.
  </Definition>
  <Definition term="file" id="file">
    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 term="folder" id="folder">
    A folder is a container for files. Folders can contain other folders and files, allowing for a hierarchical organization of data.
  </Definition>
  <Definition term="real-time synchronization" id="real-time-sync">
    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 id="external-service"/> 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 id="external-service"/> **may** also support the following in order to provide <DefinitionReference id="real-time-sync" term="real-time synchronization"/>:
- Webhooks that can notify your <DefinitionReference id="integration"/> of the following events:
  - A <DefinitionReference id="file"/> was created.
  - A <DefinitionReference id="file"/> was updated.
  - A <DefinitionReference id="file"/> was deleted.
  - A <DefinitionReference id="folder"/> was deleted.

## Updating your `package.json` file

### Finding the current interface version

The current version of the `files-readonly` interface is: <code>0.2.0</code>

You will need this version number for the next steps.

### Adding the interface as a dependency

Once you have the <DefinitionReference id="files-readonly" term="file synchronization interface"/> version, you can add it as a dependency to your <DefinitionReference id="integration"/>:

<Steps>
  <Step title="Open the package.json file">
    Open your <DefinitionReference id="integration"/>'s `package.json` file.
  </Step>
  <Step title="Add the dependencies section">
    If there is no `bpDependencies` section in your <DefinitionReference id="integration"/>'s `package.json` file, create one:

    ```json package.json {2}
    {
      "bpDependencies": {}
    }
    ```

  </Step>
  <Step title="Add the interface as a dependency">
    In the `bpDependencies` section, add the <DefinitionReference id="files-readonly" term="file synchronization interface"/> as a dependency. For example, for version `0.2.0`, you would add the following:

    ```json package.json {3}
    {
      "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 id="files-readonly" term="file synchronization interface"/> as a dependency, you can run the [`bp add`](/integrations/sdk/cli-reference.md#add) command to install it. This command will:
  - Download the interface from Botpress.
  - Install it in a directory named `bp_modules` in your <DefinitionReference id="integration"/>'s root directory.
  </Step>
</Steps>

### Adding a helper build script

To keep your <DefinitionReference id="integration"/> 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 id="integration"/>'s `package.json` file.
  </Step>
  <Step title="Add the build script">
    In the `scripts` section, add the following script:
    ```json package.json {3}
    {
      "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 id="files-readonly" term="file synchronization interface" /> and build your <DefinitionReference id="integration" />.

## Editing your integration definition file

### Adding the interface to your integration definition file

Now that the <DefinitionReference id="files-readonly" term="file synchronization 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 <DefinitionReference id="integration"/>'s `integration.definition.ts` file.
  </Step>
  <Step title="Import the interface">
    At the top of the file, import the <DefinitionReference id="files-readonly" term="file synchronization interface"/>:

    ```typescript integration.definition.ts
    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}
  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 id="external-service"/>. This will help you avoid confusion and make your <DefinitionReference id="integration"/> easier to
  understand.
</Tip>

#### Renaming actions

The <DefinitionReference id="files-readonly" term="file synchronization interface"/> defines two actions that are used to interact with the <DefinitionReference id="external-service"/>:

- `listItemsInFolder` - Used by the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> to request a list of all files and folders in a folder.
- `transferFileToBotpress` - Used by the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> to request that a file be downloaded from the <DefinitionReference id="external-service"/> 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}
.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 id="integration"/> clearer and easier to understand.
</Tip>

#### Renaming events

The <DefinitionReference id="files-readonly" term="file synchronization interface"/> interface defines these events to notify the plugin of changes in the <DefinitionReference id="external-service"/>:

- `fileCreated` - Emitted by your <DefinitionReference id="integration"/> to notify the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> that a new <DefinitionReference id="file"/> has been created in the <DefinitionReference id="external-service"/>.
- `fileUpdated` - Emitted by your <DefinitionReference id="integration"/> to notify the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> that a <DefinitionReference id="file"/> has been updated in the <DefinitionReference id="external-service"/>.
- `fileDeleted` - Emitted by your <DefinitionReference id="integration"/> to notify the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> that a <DefinitionReference id="file"/> has been deleted in the <DefinitionReference id="external-service"/>.
- `folderDeletedRecursive` - Emitted by your <DefinitionReference id="integration"/> to notify the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> that a <DefinitionReference id="folder"/> and all of its contents have been deleted in the <DefinitionReference id="external-service"/>.

<Tip>
  If the <DefinitionReference id="external-service"/> 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}
.extend(filesReadonly, () => ({
  events: {
    fileCreated: {
      name: 'pageCreated',
    },
  },
}))
```

## Implementing the interface

### Implementing the actions

#### Implementing `listItemsInFolder`

The `listItemsInFolder` action is used by the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> 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 id="file-synchronizer" term="file synchronizer plugin"/> is requesting a list of all items in the root directory of the <DefinitionReference id="external-service"/>. For root directory requests, please refer to the documentation of the <DefinitionReference id="external-service"/> 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 id="external-service"/>'s API to get the list of items in the folder. If the <DefinitionReference id="external-service"/> 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}
      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 id="external-service"/> 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 id="file-synchronizer" term="file synchronizer plugin"/> is responsible for handling recursion. Your <DefinitionReference id="integration"/> 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 id="file-synchronizer" term="file synchronizer plugin"/> expects the following schemas:
    <Expandable title="folder schema">

      ```typescript {2-4}
      type Folder = {
        id: string;
        type: "folder";
        name: string;
        parentId?: string;
        absolutePath?: string;
      }
      ```

      <ResponseField name="id" type="string" required>
        This could be a unique identifier from the <DefinitionReference id="external-service"/>, or a relative or absolute path, so long as it's unique. Your <DefinitionReference id="integration"/> must be able to resolve this identifier to the actual folder in the <DefinitionReference id="external-service"/>. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> will use this identifier to enumerate children of this folder.
      </ResponseField>
      <ResponseField name="type" type="string" required>
        This should always be `folder`.
      </ResponseField>
      <ResponseField name="name" type="string" required>
        The name of the folder. This should be the name of the folder as it appears in the <DefinitionReference id="external-service"/>.
      </ResponseField>
      <ResponseField name="parentId" type="string" optional>
        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" optional>
        The absolute path of the folder in the <DefinitionReference id="external-service"/>, if available.
      </ResponseField>
    </Expandable>
    <Expandable title="file schema">

      ```typescript {2-4}
      type File = {
        id: string;
        type: "file";
        name: string;
        parentId?: string;
        absolutePath?: string;
        sizeInBytes?: number;
        lastModifiedDate?: string;
        contentHash?: string;
      }
      ```

      <ResponseField name="id" type="string" required>
        This could be a unique identifier from the <DefinitionReference id="external-service"/>, or a relative or absolute path, so long as it's unique. Your <DefinitionReference id="integration"/> must be able to resolve this identifier to the actual file in the <DefinitionReference id="external-service"/>. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> will use this identifier to download the file.
      </ResponseField>
      <ResponseField name="type" type="string" required>
        This should always be `file`.
      </ResponseField>
      <ResponseField name="name" type="string" required>
        The name of the file. This should be the name of the file as it appears in the <DefinitionReference id="external-service"/>, including its file extension. This same name will be used to display the file in Botpress.
      </ResponseField>
      <ResponseField name="parentId" type="string" optional>
        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" optional>
        The absolute path of the file in the <DefinitionReference id="external-service"/>, if available.
      </ResponseField>
      <ResponseField name="sizeInBytes" type="number" optional>
        The size of the file in bytes, if available.
      </ResponseField>
      <ResponseField name="lastModifiedDate" type="string" optional>
        The last modified date of the file, if available. This should be an ISO 8601 date string.
      </ResponseField>
      <ResponseField name="contentHash" type="string" optional>
        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 id="external-service"/> 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 id="file-synchronizer" term="file synchronizer plugin"/> by returning the list of items. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> will then handle the rest of the synchronization process.

    ```typescript {2-3}
    return {
      items: [...mappedFolders, ...mappedFiles],
      meta: { nextToken: hasMoreItems ? nextToken : undefined },
    }
    ```

    <Note>
      If the <DefinitionReference id="external-service"/> indicates it has more items, return the pagination token in the `nextToken` field. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> 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}
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 id="file-synchronizer" term="file synchronizer plugin"/> to request that a file be downloaded from the <DefinitionReference id="external-service"/> 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 id="external-service"/>.
  </Step>
  <Step title="Download the file from the external service">
    Use the <DefinitionReference id="external-service"/>'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 id="file-synchronizer" term="file synchronizer plugin"/> as `input.fileKey`.
  </Step>
  <Step title="Yield control back to the plugin">
    Yield control back to the <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> 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}
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 id="file-synchronizer" term="file synchronizer plugin"/> can be configured to use real-time synchronization. This means that changes in the <DefinitionReference id="external-service"/> are immediately reflected in Botpress. To enable this functionality, the <DefinitionReference id="external-service"/> must support webhooks that can notify your <DefinitionReference id="integration"/> of changes in the filesystem.

#### Implementing `fileCreated`

<Steps>
  <Step title="Add a webhook handler">
    In your <DefinitionReference id="integration"/>, add a webhook handler that can receive file change notifications from the <DefinitionReference id="external-service"/>.
  </Step>
  <Step title="Map the file to the expected schema">
    In your handler, map the file to the expected schema. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> expects the following schema:
    <Expandable title="file schema">

      ```typescript {2-5}
      type File = {
        id: string;
        type: "file";
        name: string;
        absolutePath: string;
        parentId?: string;
        sizeInBytes?: number;
        lastModifiedDate?: string;
        contentHash?: string;
      }
      ```

      <ResponseField name="id" type="string" required>
        This could be a unique identifier from the <DefinitionReference id="external-service"/>, or a relative or absolute path, so long as it's unique. Your <DefinitionReference id="integration"/> must be able to resolve this identifier to the actual file in the <DefinitionReference id="external-service"/>. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> will use this identifier to download the file.
      </ResponseField>
      <ResponseField name="type" type="string" required>
        This should always be `file`.
      </ResponseField>
      <ResponseField name="name" type="string" required>
        The name of the file. This should be the name of the file as it appears in the <DefinitionReference id="external-service"/>, including its file extension. This same name will be used to display the file in Botpress.
      </ResponseField>
      <ResponseField name="absolutePath" type="string" required>
        The absolute path of the file in the <DefinitionReference id="external-service"/>. Unlike with the `listItemsInFolder` action, this field is required for the `fileCreated` event.
      </ResponseField>
      <ResponseField name="parentId" type="string" optional>
        The identifier of the parent folder.
      </ResponseField>
      <ResponseField name="sizeInBytes" type="number" optional>
        The size of the file in bytes, if available.
      </ResponseField>
      <ResponseField name="lastModifiedDate" type="string" optional>
        The last modified date of the file, if available. This should be an ISO 8601 date string.
      </ResponseField>
      <ResponseField name="contentHash" type="string" optional>
        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 id="external-service"/> 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 id="file-synchronizer" term="file synchronizer plugin"/> will then handle the rest of the synchronization process.

    ```typescript {2-3}
    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 id="integration"/>, add a webhook handler that can receive file change notifications from the <DefinitionReference id="external-service"/>.
  </Step>
  <Step title="Map the folder to the expected schema">
    In your handler, map the folder to the expected schema. The <DefinitionReference id="file-synchronizer" term="file synchronizer plugin"/> expects the following schema:
    <Expandable title="folder schema">

      ```typescript {2-5}
      type Folder = {
        id: string;
        type: "folder";
        name: string;
        absolutePath: string;
        parentId?: string;
      }
      ```

      <ResponseField name="id" type="string" required>
        This could be a unique identifier from the <DefinitionReference id="external-service"/>, or a relative or absolute path, so long as it's unique.
      </ResponseField>
      <ResponseField name="type" type="string" required>
        This should always be `folder`.
      </ResponseField>
      <ResponseField name="name" type="string" required>
        The name of the folder. This should be the name of the folder as it appears in the <DefinitionReference id="external-service"/>
      </ResponseField>
      <ResponseField name="absolutePath" type="string" required>
        The absolute path of the folder in the <DefinitionReference id="external-service"/>. Unlike with the `listItemsInFolder` action, this field is required for the `folderDeletedRecursive` event.
      </ResponseField>
      <ResponseField name="parentId" type="string" optional>
        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 id="file-synchronizer" term="file synchronizer plugin"/> will then handle the rest of the synchronization process.

    ```typescript {2-3}
    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}
await client.createEvent({
  name: 'aggregateFileChanges',
  payload: {
    modifiedItems: {
      created: [...mappedCreatedFiles],
      updated: [...mappedUpdatedFiles],
      deleted: [...mappedDeletedFilesOrFolders],
    },
  },
})
```

<Tip>
  If your <DefinitionReference id="integration"/> 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 id="file-synchronizer" term="file synchronizer plugin"/>.
</Tip>

---

# Bots-as-code

Source: https://botpress.com/docs/integrations/sdk/bots-as-code

Just like [Botpress Studio](/studio/introduction.md), 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](/studio/get-started/configure-your-workspace.md#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 title="npm"
npm install -g @botpress/cli
```

```bash title="pnpm"
pnpm install -g @botpress/cli
```

```bash title="yarn"
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
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
bp login
```

{/* TODO: add a guide on how to create a personal access token and link to it. */}

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
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
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
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](/api-reference/chat-api/introduction.md) page for more information.

To install in your bot-as-code, run the following command:

```bash
bp add chat@latest
```

Then navigate to the `bot.definition.ts` file and add the following code:

{/* TODO(driftable): This script is subject to changes and should be type-checked */}

```ts
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
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:

{/* TODO(driftable): This script is subject to changes and should be type-checked */}

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

{/* TODO: automate this reference */}

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

---

### `logout`

Logout of Botpress Cloud.

**Usage:**

```bash
bp logout
```

---

### `init`

Initialize a new project.

**Usage:**

```bash
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
bp profiles list
bp profiles ls
```

---

#### `active`

Get the profile properties you are currently using.

**Usage:**

```bash
bp profiles active
```

---

#### `use`

Set the current profile.

**Usage:**

```bash
bp profiles use my-profile
bp profiles use production
```

**Arguments:**

| Argument       | Description                                       |
| -------------- | ------------------------------------------------- |
| `profileToUse` | Profile name from $BP_BOTPRESS_HOME/profiles.json |

---

# 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](/webchat/get-started/quick-start.md) to a fully customizable [React library](/webchat/react-library/get-started.md).

<Tip>

    Looking for a way to integrate your bot in your service? Check out the [Chat API](/api-reference/chat-api/introduction.md).

</Tip>

## Getting Started

<CardGroup cols={2}>
  <Card title="Add a bot to your website" href="/webchat/get-started/quick-start.md" icon="message-square">
    Use a script tag to embed a bot in your website
  </Card>
  <Card title="React Library" href="/webchat/react-library/get-started.md" icon="simple-icons:react">
    Use the React library to build a Webchat component directly into your application
  </Card>
</CardGroup>

## Add your bot to your CMS

<CardGroup cols={3}>
  <Card title="WordPress" href="/webchat/integrations/wordpress.md" icon="simple-icons:wordpress">
    Add a bot to your WordPress website using Webchat
  </Card>
  <Card title="Wix" href="/webchat/integrations/wix.md" icon="simple-icons:wix">
    Add a bot to your Wix website using Webchat
  </Card>
  <Card title="Webflow" href="/webchat/integrations/webflow.md" icon="simple-icons: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](/webchat/integrations/wordpress.md), [Wix](/webchat/integrations/wix.md) or [Webflow](/webchat/integrations/webflow.md), see the other pages in this section for instructions on how to add your bot.

</Note>

<Info>
You will need:

- A [published bot](/studio/get-started/quick-start.md)
- Basic familiarity with HTML

</Info>

<Steps titleSize='h2'>
  <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>
      <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
      <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
    </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}
    <!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>
      <Picture alt="Webchat" class="block dark:hidden" src={webchatImg} />
      <Picture alt="Webchat" class="hidden dark:block" src={webchatDarkImg} />
    </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.

---

# 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](/webchat/get-started/quick-start.md) using Webchat v3.3
- Basic familiarity with HTML

</Info>

<Steps titleSize="h2">
  <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
    <div id="bp-embedded-webchat"></div>
    ```

  </Step>
</Steps>

<Check>Done! The Webchat window will now be visible in the element.</Check>

---

# Configure Webchat

Source: https://botpress.com/docs/webchat/get-started/configure-your-webchat

<Info>

You will need:

- A [published bot](/studio/get-started/quick-start.md)
- 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](/webchat/react-library/get-started.md).
  In this case, use the [configuration prop](/webchat/react-library/components/webchat.md#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
.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](/webchat/get-started/embedding-webchat.md)
- **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](/webchat/interact/proactive-message-bubble.md) 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](/studio/get-started/manage-your-agent/monitor.md#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](/webchat/react-library/get-started.md).

#### Allowed origins {<Tooltip tip="This feature requires a Botpress Team plan or higher."><Badge variant="team">Team</Badge></Tooltip>}

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>

---

# 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](/studio/concepts/cards/webchat.md).
</Tip>

<Info>
    You will need:

    - A website with an [embedded bot](/webchat/get-started/quick-start.md)
    - Basic familiarity with JavaScript

</Info>

## Open Webchat

To manually open Webchat:

```javascript
window.botpress.open()
```

## Close Webchat

To manually close Webchat:

```javascript
window.botpress.close()
```

## Toggle Webchat

To manually toggle Webchat:

```javascript
window.botpress.toggle()
```

This **opens** Webchat if it's closed, or **closes** Webchat if it's open.

---

# 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](/webchat/get-started/quick-start.md) using Webchat v3.3
- Basic familiarity with HTML

</Info>

<Note>
  This option isn't available if you're [embedding Webchat in a specific
  element](/webchat/get-started/embed-in-element.md).
</Note>

<Steps titleSize="h2">
  <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
    <button id="bp-toggle-chat">Toggle chat</button>
    ```

  </Step>
</Steps>

<Check>Done! This element will now toggle the Webchat window.</Check>

---

# Display proactive bubble

Source: https://botpress.com/docs/webchat/interact/proactive-message-bubble

export const lightContent = `<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://cdn.botpress.cloud/webchat/v3.3/inject.js"></script>
  <style>
  .bpWebchat { visibility: hidden !important; }
  </style>
</head>
<body>
  <script>
    window.botpress.init({
      "botId": "1291df10-9dfe-4583-8480-755c3cdbbdc8",
      "configuration": {
        "version": "v2",
        "website": {},
        "email": {},
        "phone": {},
        "termsOfService": {},
        "privacyPolicy": {},
        "color": "#3276EA",
        "variant": "solid",
        "headerVariant": "glass",
        "themeMode": "light",
        "fontFamily": "inter",
        "radius": 4,
        "feedbackEnabled": false,
        "footer": "[⚡ by Botpress](https://botpress.com/?from=webchat)",
        "soundEnabled": false,
        "proactiveMessageEnabled": true,
        "proactiveBubbleMessage": "Hi! 👋 Need help?",
        "proactiveBubbleTriggerType": "afterDelay",
        "proactiveBubbleDelayTime": 1
      },
      "clientId": "1a674b3a-fcb9-44c5-bd61-15c960fec528"
    });
  </script>
</body>
</html>`

export const darkContent = `<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://cdn.botpress.cloud/webchat/v3.3/inject.js"></script>
  <style>
  body { background: #1a1a1a; }
  .bpWebchat { visibility: hidden !important; }
  </style>
</head>
<body>
  <script>
    window.botpress.init({
      "botId": "1291df10-9dfe-4583-8480-755c3cdbbdc8",
      "configuration": {
        "version": "v2",
        "website": {},
        "email": {},
        "phone": {},
        "termsOfService": {},
        "privacyPolicy": {},
        "color": "#3276EA",
        "variant": "solid",
        "headerVariant": "glass",
        "themeMode": "dark",
        "fontFamily": "inter",
        "radius": 4,
        "feedbackEnabled": false,
        "footer": "[⚡ by Botpress](https://botpress.com/?from=webchat)",
        "soundEnabled": false,
        "proactiveMessageEnabled": true,
        "proactiveBubbleMessage": "Hi! 👋 Need help?",
        "proactiveBubbleTriggerType": "afterDelay",
        "proactiveBubbleDelayTime": 1
      },
      "clientId": "1a674b3a-fcb9-44c5-bd61-15c960fec528"
    });
  </script>
</body>
</html>`

<iframe srcDoc={lightContent} title="Proactive bubble" class="w-full rounded-xl block dark:hidden" height="200px" />
<iframe srcDoc={darkContent} title="Proactive bubble" class="w-full rounded-xl hidden dark:block" height="200px" />

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](/webchat/interact/use-custom-toggle.md)). The proactive bubble won't work if you're [embedding Webchat in an element](/webchat/get-started/embedding-webchat.md)
- A website with an [embedded bot](/webchat/get-started/quick-start.md)

</Info>

## Setup

1. From your Dashboard, go to your bot's [Webchat configuration settings.](/webchat/get-started/configure-your-webchat.md)
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.

---

# 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](/webchat/get-started/quick-start.md)
- 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
window.botpress.on('webchat:initialized', (event) => {
  setTimeout(() => {
    window.botpress.open()
  }, 500)
})
```

This waits until [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized), then [opens the Webchat window](/webchat/interact/open-close-webchat.md#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
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](/webchat/interact/listen-to-events.md#webchat-is-initialized), then [opens the Webchat window](/webchat/interact/open-close-webchat.md#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
// 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.

---

# 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](/webchat/get-started/quick-start.md)
    - Familiarity with HTML and JavaScript

</Info>

## Update user data

Use the [`window.botpress.updateUser`](/webchat/interact/reference.md#updateuser) method to update user data after your website has initialized Webchat:

```js
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](/webchat/interact/listen-to-events.md#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`](/webchat/interact/reference.md#updateuser) as soon as it fires:

```js {3-9}
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](/studio/concepts/cards/webchat.md#get-user-data) Card to access it in the [Studio](/studio/introduction.md):

<Frame>
  <Picture alt="Get User Data Card" class="block dark:hidden" src={getUserDataImg} />
  <Picture alt="Get User Data Card" class="hidden dark:block" src={getUserDataDarkImg} />
</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`](/webchat/interact/reference.md#getuser) method to access the current user data programmatically:

```js
async function getBotpressUser() {
  const user = await window.botpress.getUser()
  console.log(user)
}

getBotpressUser()
```

---

# 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](/webchat/get-started/quick-start.md), you can use the [`window.botpress.on`](/webchat/interact/reference.md#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](/webchat/get-started/quick-start.md)
    - 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}
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](/webchat/get-started/quick-start.md)) 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}
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}
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}
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}
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}
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}
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}
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](/webchat/react-library/get-started.md#step-2%3A-build-a-component)

</Info>

If you're using the [Webchat React library](/webchat/react-library/get-started.md), you can use the [`useWebchat`](/webchat/react-library/hooks/use-webchat-client.md) hook's returned `on` value to listen to events. Just add the following code at the top level of your Webchat implementation:

```jsx useWebchat
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](/webchat/react-library/components/webchat.md)—using them together will cause issues and unexpected behaviour.

If you need to use the hook, make sure you're [manually building Webchat](/webchat/react-library/get-started.md#option-2%3A-build-webchat-manually).

</Warning>

### New conversation starts

This event fires when a new conversation starts in Webchat:

```jsx highlight={4}
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}
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}
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](/studio/concepts/cards/webchat.md):

```jsx highlight={4}
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](/studio/concepts/cards/webchat.md#configure-webchat) Card:

```jsx highlight={4}
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}
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}
useEffect(() => {
  const unsubscribe = on('isTyping', (status) => {
    console.log('Bot is typing:', status)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])
```

---

# 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 titleSize="h2">
    <Step title="Add the Conversation Started Trigger">
        In your Workflow, right-click and select **Trigger**, then **Conversation Started**:

        <Frame>
        <Picture alt="Conversation Started Trigger" src={conversationStartedImg} />
        </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>
        <Picture alt="Welcome message" src={welcomeMessageImg} />
        </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>

---

# Display notification bubble

Source: https://botpress.com/docs/webchat/interact/webchat-notification

export const lightContent = `<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://cdn.botpress.cloud/webchat/v3.2/inject.js"></script>
  <style>
    :root {
      --bubble-bg: #ccddfa;
      --bubble-fg: #173569;
    }
    .bpWebchat { visibility: hidden !important; }
    .cb {
      position: fixed;
      right: 24px;
      bottom: 102px;
      z-index: 9999;
      display: none;
      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, sans-serif;
      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; }
    .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;
    }
    .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; }
    }
  </style>
</head>
<body>
  <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">x</button>
  </div>
  <script>
    window.botpress.init({
      "botId": "bba7ef77-749f-4211-88e2-25ebd8c01f9a",
      "configuration": {
        "version": "v2",
        "botName": "Notification bubble demo",
        "website": {}, "email": {}, "phone": {},
        "termsOfService": {}, "privacyPolicy": {},
        "color": "#3276EA", "variant": "solid", "headerVariant": "glass",
        "themeMode": "light", "fontFamily": "inter", "radius": 4,
        "feedbackEnabled": true,
        "footer": "[by Botpress](https://botpress.com/?from=webchat)",
        "toggleChatId": "bp-toggle-chat"
      },
      "clientId": "4a956415-2c82-4df6-8221-b8b1e5b3bc65"
    });
    (function () {
      var msgDiv = document.getElementById('msgDiv');
      var msgText = document.getElementById('msgText');
      var shown = false;
      function showBubble(text) {
        if (!msgDiv || !msgText) return;
        msgText.textContent = text || '';
        msgDiv.style.display = 'block';
      }
      function showInitial() {
        if (!shown) {
          showBubble('This is a new message sent by the bot, displayed in a notification bubble.');
          shown = true;
        }
      }
      if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', showInitial);
      } else {
        showInitial();
      }
    })();
  </script>
</body>
</html>`

export const darkContent = `<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://cdn.botpress.cloud/webchat/v3.2/inject.js"></script>
  <style>
    :root {
      --bubble-bg: #ccddfa;
      --bubble-fg: #173569;
    }
    body { background: #1a1a1a; }
    .bpWebchat { visibility: hidden !important; }
    .cb {
      position: fixed;
      right: 24px;
      bottom: 102px;
      z-index: 9999;
      display: none;
      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, sans-serif;
      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; }
    .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;
    }
    .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; }
    }
  </style>
</head>
<body>
  <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">x</button>
  </div>
  <script>
    window.botpress.init({
      "botId": "bba7ef77-749f-4211-88e2-25ebd8c01f9a",
      "configuration": {
        "version": "v2",
        "botName": "Notification bubble demo",
        "website": {}, "email": {}, "phone": {},
        "termsOfService": {}, "privacyPolicy": {},
        "color": "#3276EA", "variant": "solid", "headerVariant": "glass",
        "themeMode": "dark", "fontFamily": "inter", "radius": 4,
        "feedbackEnabled": true,
        "footer": "[by Botpress](https://botpress.com/?from=webchat)",
        "toggleChatId": "bp-toggle-chat"
      },
      "clientId": "4a956415-2c82-4df6-8221-b8b1e5b3bc65"
    });
    (function () {
      var msgDiv = document.getElementById('msgDiv');
      var msgText = document.getElementById('msgText');
      var shown = false;
      function showBubble(text) {
        if (!msgDiv || !msgText) return;
        msgText.textContent = text || '';
        msgDiv.style.display = 'block';
      }
      function showInitial() {
        if (!shown) {
          showBubble('This is a new message sent by the bot, displayed in a notification bubble.');
          shown = true;
        }
      }
      if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', showInitial);
      } else {
        showInitial();
      }
    })();
  </script>
</body>
</html>`

<Tabs>
  <Tab title="Example">
    <iframe srcDoc={lightContent} title="Message notification" class="w-full rounded-xl block dark:hidden" height="200px" />
    <iframe srcDoc={darkContent} title="Message notification" class="w-full rounded-xl hidden dark:block" height="200px" />
  </Tab>
  <Tab title="Code">
    <CodeGroup>
      ```html index.html
      <!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
      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;

              msgText.textContent = text || '';
              msgDiv.style.display = 'block';

              msgDiv.onclick = () => openNotification();

              msgDiv.focus();
              msgDiv.onkeydown = (e) => {
                  if (e.key === 'Enter' || e.key === ' ') {
                      e.preventDefault();
                      openNotification();
                  }
              };

              window.botpress.on('webchat:opened', () => {
                  if (msgDiv) msgDiv.style.display = 'none';
              });

              setTimeout(() => (msgDiv.style.display = 'none'), 15000);
          }

          if (closeBtn) {
              closeBtn.addEventListener('click', (e) => {
                  e.stopPropagation();
                  msgDiv.style.display = 'none';
              });
          }

          function extractPayload(raw) {
              let data = raw;

              if (typeof data === 'string') {
                  try { data = JSON.parse(data); } catch { /* ignore */ }
              }

              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) {
              window.botpress.on('customEvent', (payload) => {
                  const webchat = document.querySelector('iframe[title="Botpress"]');
                  const data = extractPayload(payload);

                  if (data?.eventType === 'notification' && webchat && webchat.classList.contains('bpClose')) {
                      showBubble(data.message);
                  }
              });
          }
      })();
      ```
      ```css styles.css
      :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>

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](/studio/get-started/quick-start.md)
- 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](/studio/concepts/hooks.md) section.
2. Select **Create Hook** and set its type to [Before Outgoing](/studio/concepts/hooks.md#before-outgoing).
3. Paste the following code into the Hook:

```js
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
<!-- 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]
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]
: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, 0.18);
  cursor: pointer;

  font-family:
    Roboto,
    system-ui,
    -apple-system,
    Segoe UI,
    Roboto,
    'Helvetica Neue',
    Arial;
  font-size: 15px;
  transition:
    transform 0.2s ease,
    box-shadow 0.2s ease,
    opacity 0.2s ease;
  animation: bubble-in 0.28s cubic-bezier(0.2, 0.8, 0.2, 1) both;
}

.cb:hover {
  transform: translateY(-1px);
  box-shadow: 0 12px 30px rgba(0, 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, 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, 0.18);
  color: var(--bubble-fg);
  border: 0;
  cursor: pointer;
  line-height: 1;
  font-size: 16px;
}

.cb .close-chip:hover {
  background: rgba(255, 255, 255, 0.28);
}

@keyframes bubble-in {
  from {
    transform: translateY(10px) scale(0.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>

---

# 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](/webchat/get-started/quick-start.md)
    - 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`](/webchat/interact/reference.md#sendmessage) method wrapped in an event listener:

```js
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](/webchat/interact/listen-to-events.md#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
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](/webchat/interact/listen-to-events.md#webchat-is-initialized)
2. [Opens Webchat](/webchat/interact/open-close-webchat.md#open-webchat)
3. Waits until [Webchat is ready to receive messages](/webchat/interact/listen-to-events.md#webchat-is-ready)
4. Sends the message on behalf on the user's behalf

---

# 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.md)
    - Familiarity with JavaScript

</Info>

<Steps titleSize="h3">
    <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>
          <Picture alt="Send Custom Event Card" class="block dark:hidden" src={sendCustomEventImg} />
          <Picture alt="Send Custom Event Card" class="hidden dark:block" src={sendCustomEventDarkImg} />
        </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](/studio/concepts/variables/overview.md) 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](/webchat/interact/listen-to-events.md#custom-event).

        ``` javascript index.js {3}
        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}
        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](/webchat/interact/listen-to-events.md), 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](/webchat/get-started/quick-start.md), follow the steps below to send custom events:

<Info>
    You will need:

    - A website with an [embedded bot](/webchat/get-started/quick-start.md)
    - 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`](/webchat/interact/reference.md#sendevent) method:

        ``` javascript index.js
        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](/studio/concepts/triggers.md#custom-trigger) to your bot's Workflow:

      1. In your Workflow, right-click and select **Trigger**, then **Custom Trigger**:

      <Frame>
        <Picture alt="Custom Trigger" class="block dark:hidden" src={customTriggerImg} />
        <Picture alt="Custom Trigger" class="hidden dark:block" src={customTriggerDarkImg} />
      </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>
          <Picture alt="Test Trigger" class="block dark:hidden" src={testTriggerImg} />
          <Picture alt="Test Trigger" class="hidden dark:block" src={testTriggerDarkImg} />
        </Frame>

        2. Select the <Icon icon="play" /> button to test the Custom Trigger's behaviour in the Studio's [Emulator](/studio/concepts/emulator.md).
    </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](/webchat/react-library/get-started.md), follow the steps below to send custom events:

<Info>
  You will need:

- A working React app that [implements Webchat](/webchat/react-library/get-started.md#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`](/webchat/react-library/hooks/use-webchat-client.md) hook and destructure the `client` object:

    ```jsx
    const { client } =
      useWebchat({
        clientId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        // Replace with your actual client ID
    })
    ```

    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
    const customPayload = {
        "test": "test"
    }
    ```

    Then, send the event using `client.sendEvent(customPayload)`. For example, in a button:

    <CodeGroup>

    ```jsx title="Send event button"
    <button onClick={() => client.sendEvent(customPayload)}>
      Send custom event
    </button>
    ```

    ```jsx title="Example in a full React app" expandable {17-19,23-25}
    import { Fab, Webchat, useWebchat } from '@botpress/webchat'
    import { useState } from 'react'

    function App() {
      const clientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      // 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](/studio/concepts/triggers.md#custom-trigger) to your bot's Workflow:

    1. In your Workflow, right-click and select **Trigger**, then **Custom Trigger**:

    <Frame>
      <Picture alt="Custom Trigger" class="block dark:hidden" src={customTriggerImg} />
      <Picture alt="Custom Trigger" class="hidden dark:block" src={customTriggerDarkImg} />
    </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>
      <Picture alt="Test Trigger" class="block dark:hidden" src={testTriggerImg} />
      <Picture alt="Test Trigger" class="hidden dark:block" src={testTriggerDarkImg} />
    </Frame>

    2. Select the <Icon icon="play" /> button to test the Custom Trigger's behaviour in the Studio's [Emulator](/studio/concepts/emulator.md).

  </Step>
</Steps>

<Check>Once you've re-published your bot, it'll respond to custom events.</Check>

---

# Update Webchat configuration

Source: https://botpress.com/docs/webchat/interact/update-config

You can update your [Webchat's configuration](/webchat/get-started/configure-your-webchat.md) 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](/webchat/get-started/quick-start.md)
    - Familiarity with JavaScript

</Info>

## Update configuration

To update Webchat's configuration, you can call the [`window.botpress.config`](/webchat/interact/reference.md#config) method after Webchat has been initialized:

```js
window.botpress.config({
  configuration: {},
})
```

Include any [`configuration`](/webchat/interact/reference.md#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
const webchatConfig = {
  themeMode: 'dark',
}

window.botpress.on('webchat:initialized', () => {
  window.botpress.config({ configuration: webchatConfig })
})
```

The above snippet:

1. Waits until [Webchat is initialized](/webchat/interact/listen-to-events.md#webchat-is-initalized)
2. Updates the [`themeMode`](/webchat/interact/reference.md#param-theme-mode) configuration to `dark`

---

# 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>
  <Picture alt="Missing client ID" class="block dark:hidden" src={missingClientIdImg} />
  <Picture alt="Missing client ID" class="hidden dark:block" src={missingClientIdDarkImg} />
</Frame>

- **Cause**: Client ID not provided during initialization
- **Solution**: Provide a valid client ID

### Invalid client ID

<Frame>
  <Picture alt="Invalid client ID" class="block dark:hidden" src={invalidClientIdImg} />
  <Picture alt="Invalid client ID" class="hidden dark:block" src={invalidClientIdDarkImg} />
</Frame>

- **Cause**: Provided Client ID isn't valid
- **Solution**: Use a valid Botpress Client ID

### Missing API URL

<Frame>
  <Picture alt="Missing API URL" class="block dark:hidden" src={missingApiUrlImg} />
  <Picture alt="Missing API URL" class="hidden dark:block" src={missingApiUrlDarkImg} />
</Frame>

- **Cause**: API URL not provided during initialization
- **Solution**: Provide a valid API URL

### Invalid API URL

<Frame>
  <Picture alt="Invalid API URL" class="block dark:hidden" src={invalidApiUrlImg} />
  <Picture alt="Invalid API URL" class="hidden dark:block" src={invalidApiUrlDarkImg} />
</Frame>

- **Cause**: API URL format is incorrect
- **Solution**: Use HTTPS URL format

### Missing bot ID

<Frame>
  <Picture alt="Missing bot ID" class="block dark:hidden" src={missingBotIdImg} />
  <Picture alt="Missing bot ID" class="hidden dark:block" src={missingBotIdDarkImg} />
</Frame>

- **Cause**: Bot ID not provided during initialization
- **Solution**: Provide a valid Bot ID

### Missing config URL

<Frame>
  <Picture alt="Missing config URL" class="block dark:hidden" src={missingConfigUrlImg} />
  <Picture alt="Missing config URL" class="hidden dark:block" src={missingConfigUrlDarkImg} />
</Frame>

- **Cause**: No configuration URL provided
- **Solution**: Provide a configuration URL

### Invalid config URL

<Frame>
  <Picture alt="Invalid config URL" class="block dark:hidden" src={invalidConfigUrlImg} />
  <Picture alt="Invalid config URL" class="hidden dark:block" src={invalidConfigUrlDarkImg} />
</Frame>

- **Cause**: Provided configuration URL is invalid
- **Solution**: Use a valid configuration URL

### Invalid config

<Frame>
  <Picture alt="Invalid configuration" class="block dark:hidden" src={invalidConfigImg} />
  <Picture alt="Invalid configuration" class="hidden dark:block" src={invalidConfigDarkImg} />
</Frame>

- **Cause**: Webchat configuration file is malformed
- **Solution**: Fix configuration file format

### Config access denied

<Frame>
  <Picture alt="Config access denied" class="block dark:hidden" src={configAccessDeniedImg} />
  <Picture alt="Config access denied" class="hidden dark:block" src={configAccessDeniedDarkImg} />
</Frame>

- **Cause**: Access to configuration file is restricted
- **Solution**: Check credentials and URL accessibility

## Bot Errors

### Bot is blocked

<Frame>
  <Picture alt="Bot is blocked" class="block dark:hidden" src={botIsBlockedImg} />
  <Picture alt="Bot is blocked" class="hidden dark:block" src={botIsBlockedDarkImg} />
</Frame>

- **Cause**: Bot has been temporarily paused
- **Solution**: Check your bot's [status](/studio/get-started/manage-your-agent/inspect.md)

### Quota exceeded

<Frame>
  <Picture alt="Quota exceeded" class="block dark:hidden" src={quotaExceededImg} />
  <Picture alt="Quota exceeded" class="hidden dark:block" src={quotaExceededDarkImg} />
</Frame>

- **Cause**: Bot has reached usage limits
- **Solution**: Check usage quotas and limits in [Dashboard](/studio/get-started/configure-your-workspace.md#manage-usage-quotas)

### Not a participant

<Frame>
  <Picture alt="Not a participant" class="block dark:hidden" src={notAParticipantImg} />
  <Picture alt="Not a participant" class="hidden dark:block" src={notAParticipantDarkImg} />
</Frame>

- **Cause**: User not authorized for conversation
- **Solution**: Clear browser storage and refresh

### Invalid message content type

<Frame>
  <Picture alt="Invalid message content type" class="block dark:hidden" src={invalidMessageContentTypeImg} />
  <Picture alt="Invalid message content type" class="hidden dark:block" src={invalidMessageContentTypeDarkImg} />
</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>
  <Picture alt="Network error" class="block dark:hidden" src={networkErrorImg} />
  <Picture alt="Network error" class="hidden dark:block" src={networkErrorDarkImg} />
</Frame>

- **Cause**: General network connectivity problems
- **Solution**: Check internet connection

### SSE disconnected

<Frame>
  <Picture alt="SSE disconnected" class="block dark:hidden" src={sseDisconnectedImg} />
  <Picture alt="SSE disconnected" class="hidden dark:block" src={sseDisconnectedDarkImg} />
</Frame>

- **Cause**: Server-Sent Events connection lost
- **Solution**: Refresh the page

---

# Webchat methods reference

Source: https://botpress.com/docs/webchat/interact/reference

This page contains a reference for all methods available when [injecting Webchat](/webchat/get-started/quick-start.md).

---

## `open`

The `window.botpress.open` method opens the Webchat window:

```js
window.botpress.open()
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized).

### Parameters

The `open` method takes no parameters.

### Returns

<ResponseField type="void" />

---

## `close`

The `window.botpress.close` method closes the Webchat window:

```js
window.botpress.close()
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized).

### Parameters

The `close` method takes no parameters.

### Returns

<ResponseField type="void" />

---

## `toggle`

The `window.botpress.toggle` method toggles the Webchat window open/closed depending on its current state:

```js
window.botpress.toggle()
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized).

### Parameters

The `toggle` method takes no parameters.

### Returns

<ResponseField type="void" />

---

## `updateUser`

The asynchronous `window.botpress.updateUser` method updates the data associated with the current Webchat user:

```js
await window.botpress.updateUser({
  name: '<string>',
  pictureUrl: '<string>',
  data: {},
  userKey: '<string>',
})
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#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 defaultOpen>
    <ResponseField name="id" type="string" required>
      Unique identifier for the user.
    </ResponseField>
    <ResponseField name="createdAt" type="string" required>
      User creation timestamp in ISO 8601 format.
    </ResponseField>
    <ResponseField name="updatedAt" type="string" required>
      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 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
await window.botpress.getUser()
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized).

### Parameters

The `getUser` method takes no parameters.

### Returns

<ResponseField type="Promise<User>">
  A Promise that resolves when the user information has been retrieved.
  <Expandable>
    <ResponseField name="id" type="string" required>
      Unique identifier for the user.
    </ResponseField>
    <ResponseField name="createdAt" type="string" required>
      User creation timestamp in ISO 8601 format.
    </ResponseField>
    <ResponseField name="updatedAt" type="string" required>
      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](/webchat/get-started/configure-your-webchat.md) and the current user's data.

```js
window.botpress.config({
  configuration: {},
  user: {},
})
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized).

### Parameters

<ResponseField type="object" required>
  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" deprecated>

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 type="void" />

---

## `restartConversation`

The asynchronous `window.botpress.restartConversation` method ends the current conversation and starts a new one:

```js
await window.botpress.restartConversation()
```

It becomes available after [Webchat is ready to receive messages](/webchat/interact/listen-to-events.md#webchat-is-ready).

### Parameters

The `restartConversation` method takes no parameters.

### Returns

<ResponseField 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
await window.botpress.sendMessage('<string>')
```

It becomes available after [Webchat is ready to receive messages](/webchat/interact/listen-to-events.md#webchat-is-ready).

### Parameters

<ResponseField name="message" type="string" required>
  The message to send to the bot.
</ResponseField>

### Returns

<ResponseField 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
await window.botpress.sendEvent({})
```

It becomes available after [Webchat is ready to receive messages](/webchat/interact/listen-to-events.md#webchat-is-ready).

### Parameters

<ResponseField name="event" type="object" required>
  An object containing custom data to send to the bot. Can contain any key-value pairs.
</ResponseField>

### Returns

<ResponseField 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
window.botpress.setUnreadMessageCount(123)
```

It becomes available after [Webchat has been initialized](/webchat/interact/listen-to-events.md#webchat-is-initialized).

### Parameters

<ResponseField name="count" type="number" required>
  The number of unread messages to display on the FAB.
</ResponseField>

### Returns

<ResponseField type="void" />

---

## `on`

The `window.botpress.on` method sets up an event listener for a given Webchat event:

```js
window.botpress.on('<string>', (event) => {})
```

### Parameters

<ResponseField name="type" type="string" required>

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" required>
  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 type="function">An unsubscribe function that can be called to remove the event listener.</ResponseField>

---

# 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](/studio/get-started/quick-start.md)
- 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 titleSize="h2">
    <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>
          <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
          <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
        </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](/webchat/get-started/configure-your-webchat.md) 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](/studio/get-started/quick-start.md)
- 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>
      <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
      <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
    </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">
    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>
      <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
      <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
    </Frame>

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

    ```js title="https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js" [expandable]
    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]
    <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](/webchat/get-started/configure-your-webchat.md) it to match the rest of your website's user interface.

---

# 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](/studio/get-started/quick-start.md)
- A Webflow website with a [plan that allows adding custom scripts](https://webflow.com/pricing)

</Info>

<Steps titleSize="h2">
    <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>
          <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
          <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
        </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](/webchat/get-started/configure-your-webchat.md) it 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`](/webchat/react-library/get-started.md) package targets web React. For native apps, use the WebView approach below.

</Note>

## Prerequisites

<Info>
You will need:

- A [published bot](/studio/get-started/quick-start.md)
- 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>
  <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
  <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
</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>
  <TreeFolder name="src" defaultOpen>
    <TreeFolder name="botpress" defaultOpen>
      <TreeFile name="getBotpressWebchat.js" />
      <TreeFile name="BpWidget.js" />
      <TreeFile name="BpWidget.d.ts" />
    </TreeFolder>
    <TreeFolder name="config" defaultOpen>
      <TreeFile name="botpressConfig.js" />
    </TreeFolder>
  </TreeFolder>
</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
{
  "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
npx expo install react-native-webview
```

```bash npm
npm install react-native-webview
```

```bash yarn
yarn add react-native-webview
```

```bash pnpm
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
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
/**
 * 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
/**
 * 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
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
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
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](/webchat/get-started/configure-your-webchat.md) it in Studio to match your product. For more control over the embed, see [Embed Webchat](/webchat/get-started/embedding-webchat.md) and the [Webchat interaction reference](/webchat/interact/reference.md).

---

# 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](/studio/get-started/quick-start.md)
- 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
npm install @botpress/webchat
```

```bash yarn
yarn add @botpress/webchat
```

```bash pnpm
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](/webchat/react-library/components/webchat.md) component that contains most of what you'd expect when [injecting Webchat](/webchat/get-started/quick-start.md).

With this approach, the only other component you need to import is the [Fab](/webchat/react-library/components/fab.md). Here's an example implementation:

```jsx App.jsx expandable
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
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
          defaultOpen={false}
          closeWindow={() => setIsWebchatOpen(false)}
          restartConversation={newConversation}
          disabled={false}
          configuration={headerConfig}
        />
        <MessageList
          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](/webchat/get-started/configure-your-webchat.md). 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`](/webchat/react-library/components/webchat.md#param-configuration) prop to style Webchat.

You can also use any [custom CSS you set in the Dashboard](/webchat/get-started/configure-your-webchat.md#) 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`](/webchat/react-library/components/stylesheet-provider.md) 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.

---

# 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](/webchat/get-started/quick-start.md).

<Tabs>
    <Tab title="Example">
        <LazyIframe
            src="https://botpress.github.io/docs-examples/iframe.html?args=&globals=&id=webchat--primary"
            title="Webchat component"
            height="600px"
            />
    </Tab>
    <Tab title="Code">
    ``` jsx App.jsx
    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
    ```
    </Tab>

</Tabs>

<Note>
  The `Webchat` component doesn't use the configuration set in your bot's
  [Dashboard](/webchat/get-started/configure-your-webchat.md). Instead, configure it using the
  [configuration](#configuration) prop.
</Note>

<Warning>
  The `<Webchat>` component is incompatible with the [`useWebchat` hook](/webchat/react-library/hooks/use-webchat-client.md)—using them together will cause issues and unexpected behaviour.

If you need to use the hook, make sure you're [manually building Webchat](/webchat/react-library/get-started.md#option-2%3A-build-webchat-manually).

</Warning>

## Props

<ResponseField name="clientId" type="string" required>
  Your bot's [client ID](/webchat/react-library/get-started.md#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](/webchat/get-started/configure-your-webchat.md).
  <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](/webchat/react-library/components/fab.md).
    </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>

---

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

<Tabs>
    <Tab title="Example">
        <LazyIframe
          src="https://botpress.github.io/docs-examples/iframe.html?args=&globals=&id=fab--primary"
          title="Fab component"
          height="600px"
        />
    </Tab>
    <Tab title="Code">
    ```jsx App.jsx wrap
    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>

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

---

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

<Tabs>
    <Tab title="Example">
        <LazyIframe
            src="https://botpress.github.io/docs-examples/iframe.html?args=&globals=&id=container--primary"
            title="Container component"
            height="500px"
            />
    </Tab>
    <Tab title="Code">
        ```jsx App.jsx
        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>

## 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](/webchat/react-library/components/composer.md) contains a file upload button.
</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.

<Tabs>
    <Tab title="Example">
        <LazyIframe
            src="https://botpress.github.io/docs-examples/iframe.html?args=&globals=&id=header--primary"
            title="Header component"
            height="500px"
        />
    </Tab>
    <Tab title="Code">
        ```jsx App.jsx
        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>

<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'>"
  required
>
  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.

<Tabs>
    <Tab title="Example">
        <LazyIframe
            src="https://botpress.github.io/docs-examples/iframe.html?args=&globals=&id=messagelist--primary"
            title="MessageList component"
            height="500px"
            />
    </Tab>
    <Tab title="Code">
        ```tsx App.tsx
        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>

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

---

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

<Tabs>
    <Tab title="Example">
      <LazyIframe
          src="https://botpress.github.io/docs-examples/iframe.html?args=&globals=&id=composer--primary"
          title="Composer component"
          height="500px"
          />
    </Tab>
    <Tab title="Code">
        ```jsx App.jsx wrap
        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>

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

---

# StylesheetProvider

Source: https://botpress.com/docs/webchat/react-library/components/stylesheet-provider

```jsx App.jsx
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}
    />
  )
}
```

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>

---

# 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](/webchat/react-library/components/webchat.md)—using them together will cause issues and unexpected behaviour.

If you need to use the hook, make sure you're [manually building Webchat](/webchat/react-library/get-started.md#option-2%3A-build-webchat-manually).

</Warning>

## Usage

```tsx App.tsx
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" required>
  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
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>

---

# Introduction to the ADK

Source: https://botpress.com/docs/adk-v2/get-started/introduction

TypeScript framework for building AI agents on Botpress.

import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Botpress ADK" class="block dark:hidden" src={introNewImg} />
  <Picture alt="Botpress ADK" class="hidden dark:block" src={introNewDarkImg} />
</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
adk init my-agent     # Scaffold a project
adk dev               # Run locally against your own dev bot
adk deploy            # Ship to your production bot on Botpress Cloud
```

`adk dev` starts the **Dev Console**, a local workspace for building and debugging your bot. You can also create and deploy bots right there, without the CLI.

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

---

# Quickstart

Source: https://botpress.com/docs/adk-v2/get-started/quickstart

Install the ADK and build your first ADK bot in the Dev Console.

import { Info, Check } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import CodeGroup from '@/components/CodeGroup.astro'
import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'
import LinkCard from '@/components/LinkCard.astro'

<Info>
  Before you start, you'll need:

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

</Info>

<Steps>

<Step title="Install the ADK CLI">

Install the CLI globally for your platform:

<CodeGroup>

```bash title="macOS & Linux"
curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
```

```powershell title="Windows (PowerShell)"
powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
```

</CodeGroup>

Then verify the installation:

```bash
adk --version
```

</Step>

<Step title="Sign in to Botpress">

Sign in with the CLI:

```bash
adk login
```

Or, proceed to step 3 and sign in from the Dev Console.

</Step>

<Step title="Start building in the Dev Console">

Run `adk` from anywhere to open the **Dev Console**.

```bash
adk
```

If you haven't signed in yet, the Dev Console opens to a sign-in screen. Choose **Sign in with browser**.

<Frame>
  <Picture alt="Sign in screen in the Dev Console" class="block dark:hidden" src={loginConsoleImg} />
  <Picture alt="Sign in screen in the Dev Console" class="hidden dark:block" src={loginConsoleDarkImg} />
</Frame>

From there you create, build, and deploy your bot. It also features a built-in assistant, [Agent(0)](/adk-v2/ai-native/agent0.md), that can build and debug it with you.

<Frame>
  <Picture alt="ADK Dev Console" class="block dark:hidden" src={quickstartImg} />
  <Picture alt="ADK Dev Console" class="hidden dark:block" src={quickstartDarkImg} />
</Frame>

For the full list of commands, see the [CLI reference](/adk-v2/cli/cli-reference.md).

</Step>

</Steps>

<Check>That's it. You're building with the ADK!</Check>

---

Next, learn how your project is structured and how to configure it:

<LinkCard
  href="/adk-v2/setup/configuration.md"
  title="Configuration"
  description="Project structure, models, state, and secrets."
  icon="settings"
/>

---

# Upgrading from ADK V1

Source: https://botpress.com/docs/adk-v2/get-started/upgrade-from-1x

Move an existing ADK bot from 1.x to 2.0.

Already on ADK 1.x? Run this once inside your project to upgrade:

```bash
adk project upgrade
```

---

# ADK concepts

Source: https://botpress.com/docs/adk-v2/setup/concepts

Learn the core terms that explain profiles, targets, project links, and local development.

Most ADK setup issues come from mixing together three separate ideas: who the CLI acts as, which bot a command touches, and where the Dev Console is pointed.

## Quick map

| Term | What it means |
| ---- | ------------- |
| **Profile** | Your named login. It stores a token and API URL in `~/.adk/credentials` and decides who the CLI acts as. Profiles are per-person and never committed. |
| **Project link** | The bot connection stored in `agent.json` and `agent.local.json`. It decides which workspace and bot IDs project commands use. |
| **Target** | `dev` or `prod`. The target chooses the bot: your private development bot or the shared production bot. |
| **Production bot** | The shared bot stored in `agent.json`. `adk deploy` ships code and config to this bot. |
| **Development bot** | Your private bot stored as `devId` in `agent.local.json`. `adk dev` creates it the first time you run locally. |
| **Local runtime** | The process started by `adk dev`. Your code runs on your machine, but bot state still lives in Botpress Cloud. |
| **Dev Console** | The browser UI opened by `adk dev`, `adk dashboard`, or `adk`. It can run in Local mode or Cloud mode. |
| **Integration Hub** | The Dev Console area for installing and configuring integrations and plugins. Its actions write directly to the targeted Cloud bot. |
| **Dependency snapshot** | The generated cache in `.adk/dependencies/dev.json` and `.adk/dependencies/prod.json`. It mirrors Cloud state, is gitignored, and should not be edited by hand. |
| **Workspace** | The Botpress Cloud workspace that owns your bots. |

## Three rules

1. **Your profile supplies credentials.** It does not decide which bot a project command touches.
2. **Your project link supplies bot IDs.** `agent.json` holds the shared production bot, and `agent.local.json` holds your private dev bot plus local overrides.
3. **The target chooses the bot.** `dev` and `prod` are two bots in Botpress Cloud. "Cloud" is not a third target.

## How the pieces combine

When you run a project command, the ADK combines:

```text
selected profile      project link                 command target
----------------      --------------------------   --------------
token            +    apiUrl                  +    dev  -> devId
profile apiUrl        workspaceId                  prod -> botId
                      botId
                      local devId
```

That means `adk deploy --profile work` uses the credentials from the `work` profile, but still deploys to the production bot recorded by the project. To change the bot, relink the project or use a local project override. To change the account, switch profiles.

For the file-level model, see [Project setup](/adk-v2/setup/project-setup.md). For credentials, see [Profiles](/adk-v2/setup/profiles.md).

---

# Project setup

Source: https://botpress.com/docs/adk-v2/setup/project-setup

How your project links to its bots, how dev and production targets work, and how teams share a project.

import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

Building with the ADK works the same whether you're solo or on a team:

<Note>
  **The team model:**

  - **One production bot, shared.** The whole team deploys to the same production bot.
  - **One development bot per person, private.** Each person gets their own dev bot to build against, so two people can work on the same agent without colliding.
  - **Botpress Cloud is the source of truth.** Integrations, configuration, tables, and knowledge live on each bot in Cloud, not in git.
</Note>

Even solo, your project is ready for teammates from day one.

For the vocabulary behind profiles, targets, project links, and console modes, see [ADK concepts](/adk-v2/setup/concepts.md). For the full multi-developer workflow, see [Team development](/adk-v2/setup/team-development.md).

## The project link

A linked project records which bots it talks to in two files:

| File               | Committed to git? | Holds                                              |
| ------------------ | ----------------- | -------------------------------------------------- |
| `agent.json`       | Yes               | The production link: bot ID, workspace ID, API URL |
| `agent.local.json` | No (gitignored)   | Your development bot ID, plus any local overrides   |

Your development bot ID lives in `agent.local.json`, never in `agent.json`. Keeping it out of the shared file means each person's dev bot stays private and you avoid merge conflicts.

When both files define the same link field, `agent.local.json` wins for that developer. This lets one person override the project locally without changing the shared production link.

Link a project to a production bot with `adk link`:

```bash
adk link                                # interactive: pick workspace, then bot
adk link --workspace <id> --bot <id>    # non-interactive
```

`adk link` connects to a production bot and writes `agent.json`. `adk init` runs it for you when you scaffold a project.

## Development and production targets

Most commands act on one bot. The target decides which:

```text
dev   →  your development bot
prod  →  the shared production bot
```

| Command                          | Target          | Notes                                       |
| -------------------------------- | --------------- | ------------------------------------------- |
| `adk dev`                        | dev             | Runs your agent locally against your dev bot |
| `adk chat`                       | dev             | Talks to a running `adk dev`                |
| `adk deploy`                     | prod            | Ships code and config to the production bot |
| `adk kb sync --dev` / `--prod`   | dev or prod     | One of `--dev` / `--prod` is required       |
| `adk integrations …`             | `--target` flag | Defaults to dev                             |

The target chooses the bot. In normal projects, dev and prod both live in the same Botpress Cloud workspace.

In the Dev Console, the selector in the top-right switches the target you're viewing between development and production:

<Frame>
  <Picture alt="Dev and production target selector in the Dev Console" class="block dark:hidden" src={environmentSelectorImg} />
  <Picture alt="Dev and production target selector in the Dev Console" class="hidden dark:block" src={environmentSelectorDarkImg} />
</Frame>

<Tip>
  Toggle the target in the Dev Console with <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Mac) or{' '}
  <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Windows/Linux).
</Tip>

## Creating your development bot

`adk init` and `adk link` wire up the production bot only. Your development bot doesn't exist until the first time you run `adk dev`, which creates one in Cloud and records its ID in `agent.local.json` so the same bot is reused next time.

If that dev bot is later deleted in Cloud, run `adk dev` again. The ADK clears the stale local ID and provisions a fresh development bot.

<Note>A new teammate has to run `adk dev`, not just clone the repo, to get a working development bot.</Note>

## Working as a team

The team model comes down to one thing: what gets committed and what doesn't. `adk init` sets up the right `.gitignore` for you.

| Commit (shared)                          | Ignore (per-person or generated)              |
| ---------------------------------------- | --------------------------------------------- |
| `agent.json` (the production link)       | `agent.local.json` (your dev bot + overrides) |
| `agent.config.ts`, `src/`, `package.json` | `.adk/` (generated types, logs, snapshots)    |
|                                          | `.env` files                                  |

Because integration state lives on each bot in Cloud rather than in git, each person's dev-bot integrations are their own, and only the production bot's are shared.

To join an existing project, clone it and start your own dev bot:

```bash
git clone <repo> && cd <repo>
bun install
adk login        # sign in with your own credentials
adk dev          # creates your personal development bot
```

You inherit the shared `agent.json`, so you're pointed at the team's production bot right away. Your dev bot starts empty. To copy the production bot's integration setup onto it, see [Managing dependencies](/adk-v2/setup/managing-dependencies.md).

<Note>Each teammate signs in with their own account. See [Profiles](/adk-v2/setup/profiles.md).</Note>

## Moving a project

To move a project to a different machine or workspace, export it to a portable archive and import it elsewhere:

```bash
adk export                # bundle source, config, and dependency setup into a .adk archive
adk export --no-config    # exclude integration config (omit anything that may be a secret)
adk import <archive>      # unpack into a new directory and create fresh bots
```

Local identity stays out of exported archives, and `adk import` never deploys automatically. Dependency config is included by default and can contain secret-like values, so use `adk export --no-config` when the recipient should not receive credentials or connection details.

## Validate your project

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

```bash
adk check
```

It verifies your Node.js version, runtime version, project structure, and generated types. The same checks run automatically during `adk dev` and `adk deploy`.

<Tip>For every command and flag, see the [CLI reference](/adk-v2/cli/cli-reference.md).</Tip>

---

# Profiles

Source: https://botpress.com/docs/adk-v2/setup/profiles

Manage the credentials the ADK CLI uses to act on your behalf.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

A profile is your login: an access token tied to the Botpress account you authenticated with. Profiles are per-person and never shared or committed.

A profile decides **who** the CLI acts as. It doesn't decide **which bot** a command touches: that comes from how the project is linked to its bots, covered in [Project setup](/adk-v2/setup/project-setup.md). Your login only supplies the credentials.

## Signing in

`adk login` opens a browser to authenticate and saves the result as a profile:

```bash
adk login                       # interactive sign-in
adk login --profile work        # save under a named profile
adk login --token <token>       # non-interactive (also reads $BOTPRESS_TOKEN)
```

You can also sign in from the Dev Console. Choose **Sign in with browser** to authenticate, or **Use a token instead** to paste a token:

<Frame>
  <Picture alt="Sign in screen in the Dev Console" class="block dark:hidden" src={loginConsoleImg} />
  <Picture alt="Sign in screen in the Dev Console" class="hidden dark:block" src={loginConsoleDarkImg} />
</Frame>

## Switching and removing profiles

If you work across more than one Botpress account, keep a profile for each and switch between them:

```bash
adk profiles list           # list profiles and show the current one
adk profiles set <name>     # change your default profile
adk logout --profile <name> # remove a profile
adk logout                  # remove the current profile
```

To use a different profile for a single command without changing your default, pass `--profile`:

```bash
adk deploy --profile work
```

<Note>There's no `adk profiles delete`. Remove a profile with `adk logout --profile <name>`.</Note>

For the mental model behind profiles, targets, and project links, see [ADK concepts](/adk-v2/setup/concepts.md). For every command and flag, see the [CLI reference](/adk-v2/cli/cli-reference.md).

---

# Configuration

Source: https://botpress.com/docs/adk-v2/setup/configuration

Understand your project structure and configure your agent in agent.config.ts.

import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Tree from '@/components/tree/Tree.astro'
import TreeFolder from '@/components/tree/TreeFolder.astro'
import TreeFile from '@/components/tree/TreeFile.astro'

## Project structure

Here are the key files in your project after running `adk init`:

<Tree>
  <TreeFolder name="src" defaultOpen>
    <TreeFolder name="actions">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="conversations">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="knowledge">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="tables">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="triggers">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="workflows">
      <TreeFile name="index.ts" />
    </TreeFolder>
  </TreeFolder>
  <TreeFolder name="evals">
    <TreeFile name="index.eval.ts" />
  </TreeFolder>
  <TreeFile name="agent.config.ts" />
  <TreeFile name="agent.json" />
</Tree>

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

`agent.json` links your project to its production bot. A gitignored `agent.local.json` is added for your development bot the first time you run `adk dev`. See [Project setup](/adk-v2/setup/project-setup.md) for how those work.

## `agent.config.ts`

You configure your agent in `agent.config.ts` by calling `defineConfig`:

```typescript [expandable]
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({}),
  },
  user: {
    state: z.object({}),
  },

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

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

  // Custom events
  events: {},

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

<Note>
  Integrations aren't declared here in ADK 2.0. You manage them with the `adk integrations` and `adk plugins` commands instead. See [Managing dependencies](/adk-v2/setup/managing-dependencies.md).
</Note>

### Models

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

```typescript
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 uses `auto` and lets the platform pick a default model for you.

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

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

You can also set models from the Dev Console under **Settings > LLM Config**, or override the model on a single `execute()` call:

```typescript
await execute({
  model: 'openai:gpt-4.1-2025-04-14',
  instructions: 'You are a helpful assistant.',
})
```

### State

The `state` field defines schemas for data your agent persists. There are two 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      |

Define state with Zod. The ADK generates TypeScript types from your schemas, so state access is fully typed. Use `.default()` to set initial values:

```typescript
bot: {
  state: z.object({
    totalConversations: z.number().default(0),
  }),
},
user: {
  state: z.object({
    name: z.string().optional().describe("The user's name"),
    preferredLanguage: z.string().default("en"),
  }),
},
```

<Tip>
  For reading and writing state at runtime, see [Manage state](/adk-v2/conversations/state.md).
</Tip>

### Tags

Tags are metadata you can attach to bots, users, conversations, messages, and workflows. Declare them per scope:

```typescript
bot: {
  tags: {
    plan: { title: "Plan", description: "free or paid" },
  },
},
conversation: {
  tags: {
    priority: { title: "Priority" },
  },
},
```

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

### Secrets

Secrets store sensitive values like API keys and tokens. You declare them in `agent.config.ts`, but their values are stored separately and never committed to version control:

```typescript
secrets: {
  STRIPE_KEY: { description: "Stripe API key" },
  SENTRY_DSN: { optional: true, description: "Error tracking DSN" },
},
```

Required secrets, which are the default, must be set before `adk dev` or `adk deploy` can start the bot. Optional secrets never block startup or deployment. If a required secret is added while the dev server is already running, the ADK warns until you set it.

#### Setting values

Set values with `adk secret:set`. Development and production keep separate values, so your dev keys never reach production:

```bash
adk secret:set STRIPE_KEY "sk-test-..."          # development value
adk secret:set STRIPE_KEY "sk-live-..." --prod   # production value
```

You can also manage secrets in the Dev Console under **Settings > Secrets**, for both development and production. Adding or removing a secret here writes the declaration back to `agent.config.ts`.

<Frame>
  <Picture alt="Secrets in the Dev Console" class="block dark:hidden" src={secretsConsoleImg} />
  <Picture alt="Secrets in the Dev Console" class="hidden dark:block" src={secretsConsoleDarkImg} />
</Frame>

#### Using secrets at runtime

Import `secrets` from `@botpress/runtime` and reference them directly:

```typescript
import { secrets } from '@botpress/runtime'

const res = await fetch('https://api.stripe.com/v1/charges', {
  headers: { Authorization: `Bearer ${secrets.STRIPE_KEY}` },
})

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

The `secrets` import is a typed proxy: required secrets are typed as `string`, optional ones as `string | undefined`.

<Note>Secrets are read-only at runtime. Reassigning one throws an error.</Note>

Secret keys must be `SCREAMING_SNAKE_CASE`, start with an uppercase letter, be at least two characters, have no trailing underscore, and not start with the reserved prefixes `SECRET_`, `BP_`, or `BOTPRESS_`.

### Configuration values

The `configuration` field defines static, deploy-time settings. Unlike secrets, these aren't sensitive. Unlike state, they're read-only at runtime:

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

Set values from the CLI, with separate development and production values:

```bash
adk config                                          # fill missing values interactively
adk config:set supportEmail "help@mycompany.com"         # development value
adk config:set supportEmail "help@mycompany.com" --prod  # production value
adk config:get supportEmail                         # read a value
```

You can also edit these in the Dev Console:

<Frame>
  <Picture alt="Configuration values in the Dev Console" class="block dark:hidden" src={configVariablesConsoleImg} />
  <Picture alt="Configuration values in the Dev Console" class="hidden dark:block" src={configVariablesConsoleDarkImg} />
</Frame>

Read configuration at runtime the same way as secrets:

```typescript
import { configuration } from '@botpress/runtime'

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

### Custom events

The `events` field defines custom events your agent can emit and subscribe to:

```typescript
events: {
  orderPlaced: {
    description: "Fired when an order is placed",
    schema: z.object({
      orderId: z.string().describe("The placed order's ID"),
      total: z.number().describe('Order total in USD'),
    }),
  },
},
```

You can then listen for these events in triggers and conversations. See [Set up triggers](/adk-v2/external/triggers.md).

### Evals

The `evals` field configures how your agent's automated tests run:

```typescript
evals: {
  idleTimeout: 30000,
  judgeModel: "openai:gpt-4o",
},
```

| Field         | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| `idleTimeout` | Milliseconds to wait for the agent to respond before timing out |
| `judgeModel`  | Model used for LLM judge assertions                             |

<Tip>For the full testing workflow, see [Write and run evals](/adk-v2/testing/evals.md).</Tip>

---

# Managing dependencies

Source: https://botpress.com/docs/adk-v2/setup/managing-dependencies

Add, configure, and promote the integrations and plugins your agent depends on.

import { Note, Tip } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

Your agent depends on two kinds of external resources:

- **Integrations** connect your agent to a channel or service, like Webchat, Slack, Linear, or Stripe. You browse and install them from the Botpress Hub.
- **Plugins** are reusable behaviors provided by Botpress, like human handoff or analytics. A plugin adds logic to your bot and builds on integrations to reach the outside world.

## How dependencies work

In ADK 2.0, **Botpress Cloud is the source of truth** for your dependencies, stored separately for each bot. Since your development bot is private to you, its integrations are yours alone; the production bot holds the shared, deployed set.

You manage that state from two interchangeable places, and both write to Cloud directly:

- The CLI (`adk integrations` and `adk plugins`).
- The Dev Console's **Integration Hub**.

The ADK keeps a local cache of installed dependencies in `.adk/dependencies/dev.json` and `.adk/dependencies/prod.json`. These snapshots are generated mirrors of Cloud state for fast reads, offline status, code generation, and deploy checks. They are gitignored, may contain config values, and should never be edited or committed. If a snapshot is stale or corrupt, the ADK refreshes it from Cloud.

You also no longer declare integrations in `agent.config.ts`.

<Note>
  Upgrading a project from ADK 1.x? Run `adk project upgrade` once to move your dependencies onto Cloud. See [Upgrading from ADK V1](/adk-v2/get-started/upgrade-from-1x.md).
</Note>

## Adding integrations

Browse the catalog and install from the Integration Hub in the Dev Console, no CLI required:

<Frame>
  <Picture alt="Integration Hub in the Dev Console" class="block dark:hidden" src={integrationsConsoleImg} />
  <Picture alt="Integration Hub in the Dev Console" class="hidden dark:block" src={integrationsConsoleDarkImg} />
</Frame>

Or use the CLI. Commands default to your development bot; pass `--target prod` to act on production instead:

```bash
adk integrations search linear           # find integrations in the catalog
adk integrations add linear              # install the latest version
adk integrations add stripe@1.4.2        # pin a specific version
adk integrations list                    # see what's installed
adk integrations remove linear           # uninstall
```

Reference a version with `name@latest` (the default) or `name@version` (for example, `stripe@1.4.2`).

## Configuring integrations

Most integrations need configuration, such as API keys or an OAuth connection, before they can run. Configure them in the Dev Console:

<Frame>
  <Picture alt="Integration configuration in the Dev Console" class="block dark:hidden" src={integrationConfigConsoleImg} />
  <Picture alt="Integration configuration in the Dev Console" class="hidden dark:block" src={integrationConfigConsoleDarkImg} />
</Frame>

Or from the CLI:

```bash
adk integrations configure notion --set apiKey=secret_...
adk integrations enable notion
adk integrations disable notion
```

Integration configuration is stored on Botpress Cloud, not in your project files. Your development and production bots each have their own, so you can use different keys per target. OAuth integrations are connected in the Botpress Control Panel rather than with a key.

## Dependency status

Every dependency resolves to one status, which the CLI and Dev Console both report:

| Status          | Meaning                                                        |
| --------------- | -------------------------------------------------------------- |
| `available`     | Installed, configured, and ready to use                        |
| `disabled`      | Installed but turned off; it won't run                         |
| `unconfigured`  | Installed but missing required configuration or a connection   |
| `unresolved`    | The requested version or resource couldn't be resolved         |
| `not_installed` | Declared but not installed on this bot                         |
| `errored`       | Failed to load                                                 |

Missing required config and pending OAuth or connection setup both appear as `unconfigured`. The CLI may include `missingFields` or an authorization-pending hint to explain what is blocking the dependency.

Check status any time:

```bash
adk integrations status
```

`adk deploy` blocks when an **enabled** dependency is `unconfigured`, `unresolved`, `not_installed`, or `errored`, so you don't ship a broken integration. Disabled dependencies ship inert and never block. To deploy anyway, disable the dependency or pass `adk deploy --allow-unconfigured`.

## Promoting from development to production

The everyday loop is to build an integration on your development bot, then promote it to production. `adk integrations copy` reconciles one bot's dependencies to match another's. Always preview with `--dry-run` first:

```bash
adk integrations copy --from dev --to prod --dry-run   # preview the changes
adk integrations copy --from dev --to prod --yes       # apply them
```

`copy` works in either direction. To seed a fresh development bot with the production setup, reverse it:

```bash
adk integrations copy --from prod --to dev
```

The source bot is never modified. The target bot is reconciled to match the source, so review the dry run before applying, especially when it includes removals.

`copy` moves integrations and plugins, not your agent code, table rows, knowledge data, or conversations. Shipping code is a separate step: `adk deploy`.

## Automation tips

For scripts and coding agents, prefer machine-readable output and explicit targets:

```bash
ADK_TARGET=prod adk integrations status --format json
adk integrations copy --from dev --to prod --dry-run --format json
```

Use `--yes` only after reviewing the dry run. Do not edit files under `.adk/dependencies/`; refresh or mutate dependencies through the CLI or Dev Console instead.

## Plugins

Where an integration connects your bot to a service, a plugin adds reusable behavior on top of it. For a worked example, see [HITL with Desk](/adk-v2/advanced/desk-hitl.md), which uses the `desk-hitl` plugin to hand conversations off to a human agent.

`adk plugins` mirrors the full set of integration verbs (`add`, `remove`, `configure`, `enable`, `disable`, `list`, `status`, `copy`, and more):

```bash
adk plugins add <name>
adk plugins configure <alias> --set key=value
```

<Tip>For every dependency command and flag, see the [CLI reference](/adk-v2/cli/cli-reference.md).</Tip>

---

# Dev Console overview

Source: https://botpress.com/docs/adk-v2/setup/dev-console

Understand Dev Console modes, targets, and what each surface can do.

import { Note, Tip } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

The Dev Console is the browser UI for building and inspecting an ADK agent. It opens during `adk dev`, and you can also open it with `adk dashboard` or by running `adk` interactively.

The console has two independent ideas:

| Idea | Values | What it decides |
| ---- | ------ | --------------- |
| **Console mode** | Local or Cloud | Where the console is pointed and which actions are available |
| **Target** | `dev` or `prod` | Which bot's Cloud state the console shows or changes |

## Local mode

Local mode is attached to a project running with `adk dev`. Your agent code runs locally, while conversations, integrations, config, tables, knowledge, and other bot state still live on the selected Cloud bot.

In Local mode, you can switch between the `dev` and `prod` targets:

<Frame>
  <Picture alt="Dev and production target selector in the Dev Console" class="block dark:hidden" src={environmentSelectorImg} />
  <Picture alt="Dev and production target selector in the Dev Console" class="hidden dark:block" src={environmentSelectorDarkImg} />
</Frame>

Use `dev` for everyday local development. Switch to `prod` when you need to inspect production bot state from the same local project context.

## Cloud mode

Cloud mode opens against a deployed production bot without a local project backend. It is always `prod`, and actions that require local source context are unavailable.

Cloud mode relies on metadata published by `adk deploy`, so an ADK bot must be deployed at least once before the console can show its source-shaped definitions, such as actions, workflows, triggers, tables, knowledge, and config variables.

<Note>
  Cloud mode is useful for inspecting a deployed ADK bot. Use Local mode when you are actively developing, testing, or promoting changes between dev and prod.
</Note>

## Console areas

This is a high-level map of the Dev Console's top-level areas. Some items are only available in Local mode or can be hidden by feature flags.

| Area | Use it for | Related docs |
| ---- | ---------- | ------------ |
| Agent Map | Visualize how actions, workflows, triggers, and conversations connect | [Agent Map](/adk-v2/testing/agent-map.md) |
| Chat | Test conversations and inspect agent steps during each turn | [Set up conversations](/adk-v2/conversations/setup.md), [Agent steps](/adk-v2/testing/agent-steps.md) |
| Actions | Inspect actions exposed by your agent | [Create actions](/adk-v2/external/actions.md) |
| Workflows | Inspect workflows and workflow runs | [Create workflows](/adk-v2/workflows/create.md), [Use workflow steps](/adk-v2/workflows/steps.md) |
| Triggers | Inspect trigger definitions and connected events | [Set up triggers](/adk-v2/external/triggers.md) |
| Webchat Components | Preview custom UI components used in Webchat | [Use custom components](/adk-v2/conversations/custom-components.md) |
| RAG Search | Test knowledge retrieval against your bot's knowledge bases | [Knowledge bases](/adk-v2/data/knowledge.md) |
| Evals | Run and inspect automated conversation tests | [Write and run evals](/adk-v2/testing/evals.md) |
| Knowledge | Inspect knowledge bases connected to the selected bot | [Knowledge bases](/adk-v2/data/knowledge.md) |
| Tables | Inspect structured data connected to the selected bot | [Tables](/adk-v2/data/tables.md) |
| Files | Inspect files available to the selected bot | [Knowledge bases](/adk-v2/data/knowledge.md) |
| Conversations | Inspect conversation history | [Manage conversation lifecycle](/adk-v2/conversations/lifecycle.md) |
| Analytics | Review aggregate behavior such as volume, latency, token usage, and cost | [Analytics](/adk-v2/testing/analytics.md) |
| Traces | Debug handlers, tool calls, LLM calls, and runtime spans | [Debug with logs and traces](/adk-v2/testing/debugging.md) |
| Logs | Read runtime log output | [Debug with logs and traces](/adk-v2/testing/debugging.md) |
| Agent Config | View and update configuration values | [Configuration](/adk-v2/setup/configuration.md) |
| Integrations | Manage integrations and plugins | [Managing dependencies](/adk-v2/setup/managing-dependencies.md) |

Cloud mode is more limited because there is no local project backend. Use Local mode when you need source-aware actions or live local runtime data.

<Tip>
  Toggle the target in the Dev Console with <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Mac) or{' '}
  <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Windows/Linux).
</Tip>

---

# Team development

Source: https://botpress.com/docs/adk-v2/setup/team-development

Share one production bot while each teammate works on a private development bot.

The ADK team model is simple:

- **One production bot, shared.** The team commits `agent.json` and deploys to the same production bot.
- **One development bot per person, private.** Each teammate runs `adk dev` to create and reuse their own dev bot.
- **Botpress Cloud is the source of truth.** Integrations, configuration, tables, and knowledge live on each bot in Cloud, not in git.

This lets several people work on the same agent without overwriting each other's local runtime or dev-bot integration setup.

## What to commit

`adk init` scaffolds the right `.gitignore` for the team model.

| Commit | Ignore |
| ------ | ------ |
| `agent.json` | `agent.local.json` |
| `agent.config.ts` | `.adk/` |
| `src/` | `.env` files |
| `package.json` and lockfiles | generated logs, traces, snapshots, and types |

`agent.json` contains the shared production link. `agent.local.json` contains your private `devId` and any local overrides, so it stays out of git.

<Note>
  `.adk/` is generated and may include dependency snapshots with config values. Do not edit it by hand or commit it.
</Note>

## Start a new project

For a new project, create the agent and link it to a production bot:

```bash
adk init my-agent
cd my-agent
adk dev
```

`adk init` links the production bot through `agent.json`. The first `adk dev` creates your private development bot and records it in `agent.local.json`.

## Join an existing project

For an existing team repo, clone it and create your own dev bot:

```bash
git clone <repo>
cd <repo>
bun install
adk login
adk dev
```

You inherit the team's production bot from `agent.json`. Your dev bot starts as your own Cloud bot, so it does not automatically include every integration configured on production.

To seed your dev bot from production, copy dependency state:

```bash
adk integrations copy --from prod --to dev --dry-run
adk integrations copy --from prod --to dev --yes
```

## Promote dependency changes

Build and test integrations on your dev bot first:

```bash
adk integrations add slack
adk integrations configure slack --set botToken=...
adk integrations status
```

When the dependency setup is ready, promote it to production:

```bash
adk integrations copy --from dev --to prod --dry-run
adk integrations copy --from dev --to prod --yes
adk deploy
```

`copy` moves integration and plugin state between bots. It does not move code, table rows, knowledge data, or conversations. Shipping code is `adk deploy`.

The source bot is never modified. The target bot is reconciled to match the source, so always review the dry run before using `--yes`, especially when the plan includes removals.

## Move or hand off a project

Use export and import when you need a portable archive, a new workspace, or a handoff outside the current git repo:

```bash
adk export
adk export --no-config
adk import <archive>
```

`adk export` includes dependency config by default, and those values may include secrets. Use `adk export --no-config` when the recipient should not receive credentials or connection details.

`adk import` creates fresh bots unless you pass existing bot IDs. It does not deploy automatically.

<Tip>
  For the vocabulary behind profiles, targets, and project links, see [ADK concepts](/adk-v2/setup/concepts.md).
</Tip>

---

# Set up conversations

Source: https://botpress.com/docs/adk-v2/conversations/setup

Handle user messages across channels.

import { Info, Tip } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import CodeGroup from '@/components/CodeGroup.astro'
import Tree from '@/components/tree/Tree.astro'
import TreeFolder from '@/components/tree/TreeFolder.astro'
import TreeFile from '@/components/tree/TreeFile.astro'

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
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 integrations add webchat`.

<Frame>
  <Picture alt="Chat page in the Dev Console" class="block dark:hidden" src={agentStepsImg} />
  <Picture alt="Chat page in the Dev Console" class="hidden dark:block" src={agentStepsDarkImg} />
</Frame>

## Channel matching

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

<CodeGroup>

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

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

```ts title="Array of channels" {2-5}
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
// channel: "*" gives message.payload as unknown
handler: async ({ message }) => {
  const text = message.payload.text // ❌ TypeScript error
}

// channel: "webchat.channel" gives a fully typed message.payload
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:

<Tree>
  <TreeFolder name="src/conversations" defaultOpen>
    <TreeFile name="webchat.ts" comment="Webchat messages" />
    <TreeFile name="slack.ts" comment="Slack messages" />
    <TreeFile name="support.ts" comment="Support channel" />
  </TreeFolder>
</Tree>

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
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](/adk-v2/workflows/create.md), [lifecycle management](/adk-v2/conversations/lifecycle.md), 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
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`.

## Controlling interruptions

By default, when a new event arrives while your handler is still running, it interrupts the current run and starts a new one. Add `shouldInterrupt` to decide which events are allowed to do that. Return `true` to interrupt, or `false` to let the current run finish and process the event afterwards:

```typescript
export default new Conversation({
  channel: 'webchat.channel',
  shouldInterrupt: (props) => {
    // Let the current run finish; queue new user messages instead of interrupting.
    if (props.kind === 'message') return false
    return true
  },
  handler: async ({ execute }) => {
    await execute({ instructions: 'You are a helpful assistant.' })
  },
})
```

`shouldInterrupt` runs synchronously for each candidate event. Returning `false` for everything puts the conversation in "let me finish my turn" mode, where messages queue up and run one at a time.

## Conversation state

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

```typescript {3-6}
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](/adk-v2/conversations/state.md).
</Tip>

---

# Run AI agents in a conversation

Source: https://botpress.com/docs/adk-v2/conversations/ai-execution

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

import { Note, Tip } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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 {4-6}
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 {3,8-12}
// 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 {6}
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](/adk-v2/data/knowledge.md).
</Tip>

## Tools

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

```typescript {6}
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](/adk-v2/conversations/tools.md).

## Exits

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

```typescript
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
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
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
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
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
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
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
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](/adk-v2/testing/debugging.md).

<Frame>
  <Picture alt="Traces view in Dev Console" class="block dark:hidden" src={tracesViewImg} />
  <Picture alt="Traces view in Dev Console" class="hidden dark:block" src={tracesViewDarkImg} />
</Frame>

---

# Define tools

Source: https://botpress.com/docs/adk-v2/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
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 {10}
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 {6-15,19}
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
// 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
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
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 {8}
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](/adk-v2/external/actions.md) 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 {9}
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](/adk-v2/workflows/create.md) for more information.</Tip>

## Calling actions from tools

Tools can call actions for reusable logic:

```typescript {8}
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
  },
})
```

---

# Send messages and content

Source: https://botpress.com/docs/adk-v2/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
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](/webchat/get-started/introduction.md), 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](/adk-v2/conversations/custom-components.md) 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
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
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
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
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
await conversation.startTyping()
await conversation.stopTyping()
```

## Conversation tags

Read and write metadata tags on the conversation:

```typescript
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`. See [Configuration](/adk-v2/setup/configuration.md#tags) for more information.
</Note>

## Loading a conversation by ID

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

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

---

# Use custom components

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

Build and render custom React UI inside Webchat.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

Custom components let you render your own React UI inside [Webchat](/webchat/get-started/introduction.md). 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.

<Frame>
  <Picture alt="Custom Webchat components rendered in the Dev Console" class="block dark:hidden" src={customComponentsImg} />
  <Picture alt="Custom Webchat components rendered in the Dev Console" class="hidden dark:block" src={customComponentsDarkImg} />
</Frame>

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()`

## Add from the Component Registry

The Dev Console includes a Component Registry: a catalog of ready-made components you can browse, preview, and add to your bot. When you add one, the ADK copies its source into your project, generates the `CustomComponent` wrapper with metadata, and can wire it into the conversation that should use it.

To build your own component instead, follow the steps below.

## 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
// 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 19 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
// 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 {7-18}
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" {5}
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 {6}
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
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, 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** - the `.bp.tsx` is bundled 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.
- **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                               | Relying on global/project CSS classes        | Import component CSS directly, use inline styles, or define styles inside the component |
| 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-v2/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 {9-12}
import { Conversation, z } from '@botpress/runtime'

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

When the expire timer fires, the framework runs this sequence:

1. **Race guard check**: did the user send a message after this expiration was scheduled? If yes, skip silently, since timers are already rescheduled.
2. **Your handler runs** with `type: "expire"`.
3. **Framework cleanup** runs in order:
   1. Cancel active workflows
   2. Cancel pending nudge
   3. Set `session.status` to `expired`
   4. Tag the conversation
   5. Reset user state
   6. Clear the LLM transcript
4. **Done.** The next message 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
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
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
lifecycle: {
  nudge: { after: "10m", interval: "30m", max: 2 },
}
```

### Expiration-only (no nudges)

Silently expire after inactivity without reminders:

```typescript
lifecycle: {
  expire: { after: "1h" },
}
```

### Different timeouts per channel

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

```typescript
// 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.

---

# Manage state

Source: https://botpress.com/docs/adk-v2/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 {6-10,12-18}
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 {5-8}
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, so 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
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
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
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
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
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
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
import { bot, user } from '@botpress/runtime'

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

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

```typescript
handler: async ({ conversation }) => {
  conversation.tags.priority = 'high'
}
```

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

```typescript
const owner = conversation.tags['webchat:owner']
```

## Bot and user identity

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

```typescript
import { bot, user } from '@botpress/runtime'

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

### User profile fields

Beyond custom state, the `user` object has built-in profile fields you can read and write at runtime: `name`, `pictureUrl`, `properties`, and `attributes`. Updates are saved automatically:

```typescript
import { user } from '@botpress/runtime'

user.name = 'Ada Lovelace'
user.pictureUrl = 'https://example.com/ada.png'
```

---

# Create workflows

Source: https://botpress.com/docs/adk-v2/workflows/create

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

import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Workflows page in Dev Console" class="block dark:hidden" src={workflowsConsoleImg} />
  <Picture alt="Workflows page in Dev Console" class="hidden dark:block" src={workflowsConsoleDarkImg} />
</Frame>

### Persistent state

Add a `state` schema to carry data across the workflow's steps and retries. State is persisted between executions:

```typescript
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
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
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
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
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
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
await instance.cancel()
```

### Set timeout

Extend or change the workflow timeout:

```typescript
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
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
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
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
export default new Workflow({
  name: 'longProcess',
  timeout: '1h',
  handler: async ({ step }) => {
    // ...
  },
})
```

For workflows that need to run longer than 5 minutes, use [steps](/adk-v2/workflows/steps.md). 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`) |

---

# Use workflow steps

Source: https://botpress.com/docs/adk-v2/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
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
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
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
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
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
await step.listen('wait-for-payment')
```

## Fail and abort

Use `.fail()` or `.abort()` to stop execution explicitly:

```typescript
// 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
import ProcessingWorkflow from '../workflows/processing'

const result = await step.executeWorkflow('process-data', ProcessingWorkflow, { data: inputData })
```

Or wait for an already-running workflow:

```typescript
const childWorkflow = await ChildWorkflow.start({})
const result = await step.waitForWorkflow('wait-for-child', childWorkflow.id)
```

## Parallel processing

### `map`

Process an array of items and collect results. Set `concurrency` to run them in parallel; it defaults to `1` (one at a time):

```typescript
const results = await step.map('process-users', users, async (user, { i }) => await processUser(user), {
  concurrency: 5,
  maxAttempts: 3,
})
```

### `forEach`

Process items without collecting results. Like `map`, `concurrency` defaults to `1`; raise it to run in parallel:

```typescript
await step.forEach('notify-users', users, async (user) => await sendNotification(user), { concurrency: 10 })
```

### `batch`

Process items in sequential batches:

```typescript
await step.batch('bulk-insert', records, async (batch) => await database.bulkInsert(batch), { batchSize: 100 })
```

---

# Request and notify from workflows

Source: https://botpress.com/docs/adk-v2/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 {5-14}
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
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
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
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
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
if (props.type === 'workflow_callback') {
  const { status, output, error } = props.completion
  if (status === 'completed') {
    await props.conversation.send({
      type: 'text',
      payload: { text: `Workflow finished: ${JSON.stringify(output)}` },
    })
  } else {
    await props.conversation.send({
      type: 'text',
      payload: { text: `Workflow ${status}: ${error ?? 'unknown error'}` },
    })
  }
  return
}
```

`props.completion.status` is one of `completed`, `failed`, `canceled`, or `timed_out`. `output` is set on success; `error` holds the failure message for the other statuses.

---

# Create actions

Source: https://botpress.com/docs/adk-v2/external/actions

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

import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Actions page in Dev Console" class="block dark:hidden" src={actionsConsoleImg} />
  <Picture alt="Actions page in Dev Console" class="hidden dark:block" src={actionsConsoleDarkImg} />
</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 {3}
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
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
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
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
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](/adk-v2/conversations/tools.md) 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 {8}
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
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
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](/api-reference/runtime-api/getting-started.md)'s [`callAction`](/api-reference/runtime-api/openapi/callAction.md) endpoint. External services can call your agent's actions over HTTP:

```bash
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-v2/external/triggers

React to events from integrations and custom events.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Triggers page in Dev Console" class="block dark:hidden" src={triggersConsoleImg} />
  <Picture alt="Triggers page in Dev Console" class="hidden dark:block" src={triggersConsoleDarkImg} />
</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 {4-8}
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"
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"
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 {8-10}
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,
      })
    }
  },
})
```

---

# Tables

Source: https://botpress.com/docs/adk-v2/data/tables

Define and query structured data storage.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import CodeGroup from '@/components/CodeGroup.astro'

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
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>
  <Picture alt="Tables page in Dev Console" class="block dark:hidden" src={tablesConsoleImg} />
  <Picture alt="Tables page in Dev Console" class="hidden dark:block" src={tablesConsoleDarkImg} />
</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
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 {7,9-10}
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
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
import OrderTable from '../tables/order-table'

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

### Find rows

```typescript
const { rows } = await OrderTable.findRows({
  filter: { status: 'pending' },
  orderBy: 'createdAt',
  orderDirection: 'desc',
  limit: 10,
})
```

### Get a single row

```typescript
const row = await OrderTable.getRow({ id: 42 })
```

### Update rows

```typescript
await OrderTable.updateRows({
  rows: [{ id: orders[0].id, status: 'completed' }],
})
```

### Upsert rows

Insert or update based on a key column:

```typescript
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 definition and the `upsertRows` call, it defaults to `id`.</Note>

### Delete rows

<CodeGroup>

```typescript title="Delete rows by name"
await OrderTable.deleteRows({ status: 'cancelled' })
```

```typescript title="Delete rows by ID"
await OrderTable.deleteRowIds([1, 2, 3])
```

```typescript title="Delete all rows"
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
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
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
const { rows } = await TicketTable.findRows({
  search: 'VPN connection issues',
  limit: 10,
})
```

Combine with filters for hybrid queries:

```typescript
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
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
// 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      |

---

# Knowledge bases

Source: https://botpress.com/docs/adk-v2/data/knowledge

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

import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Knowledge page in Dev Console" class="block dark:hidden" src={knowledgeConsoleImg} />
  <Picture alt="Knowledge page in Dev Console" class="hidden dark:block" src={knowledgeConsoleDarkImg} />
</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 {10}
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
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
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 [Managing dependencies](/adk-v2/setup/managing-dependencies.md)).

```typescript
const DocsSource = DataSource.Website.fromWebsite('https://example.com', {
  fetch: 'integration:browser',
})
```

### Website from llms.txt

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

```typescript
const DocsSource = DataSource.Website.fromLlmsTxt('https://example.com/llms.txt')
```

### Website from specific URLs

Index a fixed list of pages:

```typescript
const DocsSource = DataSource.Website.fromUrls([
  'https://example.com/pricing',
  'https://example.com/faq',
  'https://example.com/terms',
])
```

### Website source options

`fromSitemap`, `fromWebsite`, and `fromLlmsTxt` accept these 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 crawl depth (1–20, default: 20)                                                                                        |
| `tags`     | `object \| function` | Extra tags applied to every indexed file. Reserved KB/source identity tags are ignored.                                         |

`fromUrls` skips crawling-specific options like `filter`, `maxPages`, and `maxDepth`, since you provide the exact list of pages to index. It still supports shared options like `id`, `fetch`, and `tags`.

### Directory

Index files from a local directory:

```typescript
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     |
| `tags`   | `object \| function`            | Extra tags applied to every indexed file  |

## 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
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)
}
```

`limit` caps how many passages come back (1–50, default 20). `contextDepth` controls how many neighboring chunks are included around each match (1–20, default 4).

## 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](/adk-v2/workflows/create.md):

```typescript
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
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
await ProductDocs.refreshSource('my-source-id', { force: true })
```

---

# Write and run evals

Source: https://botpress.com/docs/adk-v2/testing/evals

Automated conversation tests for your agent.

import Frame from '@/components/Frame.astro'

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
import { Eval } from '@botpress/evals'

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
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
{
  event: {
    payload: { orderId: "ord-123", total: 49.99 },
  },
  assert: {
    response: [{ contains: "order" }],
  },
}
```

Assert the agent doesn't respond:

```typescript
{
  user: "ok thanks",
  expectSilence: true,
}
```

Run a turn in a fresh conversation under the same user. The prior transcript is gone, so anything the agent recalls has to come from user-scoped state, not conversation context. This is ignored on the first turn:

```typescript
{
  user: "What's my name?",
  newConversation: true,
  assert: {
    response: [{ contains: "Alice" }],
  },
}
```

## 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                                                    |
| `{ 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
assert: {
  state: [
    { path: "messageCount", changed: true },
    { path: "topic", equals: "weather" },
  ],
}
```

### Workflows

Assert on workflow state:

```typescript
assert: {
  workflow: [
    { name: "processOrder", entered: true },
    { name: "processOrder", completed: true },
  ],
}
```

### Timing

Assert on response time:

```typescript
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
assert: {
  response: [
    { llm_judge: "The response is polite and professional" },
    { llm_judge: "The response correctly identifies the user's issue" },
  ],
}
```

Configure the judge model 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
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
setup: {
  workflow: {
    trigger: "onboarding",
    input: { userId: "user123" },
  },
},
```

### Outcome

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

```typescript
new Eval({
  name: 'full-flow',
  conversation: [{ user: 'Create a ticket for VPN issues' }, { user: 'Set priority to high' }],
  outcome: {
    state: [{ path: 'ticketCreated', equals: true }],
    workflow: [{ name: 'createTicket', completed: true }],
  },
})
```

## Configure eval behavior

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

```typescript
evals: {
  judgeModel: "openai:gpt-4o",
  idleTimeout: 30000,
},
```

| Option        | Type          | Description                                                    |
| ------------- | ------------- | -------------------------------------------------------------- |
| `judgeModel`  | `string`      | Model for `llm_judge` assertions. Defaults to `"fast"`         |
| `idleTimeout` | `number` (ms) | How long to wait for the agent to respond. Defaults to `30000` |

Override `idleTimeout` on a specific eval:

```typescript
new Eval({
  name: 'quality-check',
  options: {
    idleTimeout: 60000,
  },
  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
new Eval({
  name: 'greeting',
  tags: ['smoke', 'core'],
  conversation: [
    /* ... */
  ],
})
```

```bash
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
new Eval({
  name: 'fix-for-ticket-priority-bug',
  type: 'regression',
  conversation: [
    /* ... */
  ],
})
```

```bash
adk evals --type regression    # Run only regression evals
```

## Run evals

Runs stream results live, so you see each assertion pass or fail as it happens instead of waiting for the whole suite. A failed assertion is reported as a failure while the rest of the suite keeps running.

From the CLI:

```bash
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
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>
  <Picture alt="Evals page in Dev Console" class="block dark:hidden" src={evalsConsoleImg} />
  <Picture alt="Evals page in Dev Console" class="hidden dark:block" src={evalsConsoleDarkImg} />
</Frame>

---

# Agent steps

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

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

import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Agent Steps panel in Dev Console" class="block dark:hidden" src={agentStepsImg} />
  <Picture alt="Agent Steps panel in Dev Console" class="hidden dark:block" src={agentStepsDarkImg} />
</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](/adk-v2/testing/debugging.md) for more on the Traces view.

Agent Steps follows one turn at a time. To see how your agent is wired overall, before following any single run, use the [Agent Map](/adk-v2/testing/agent-map.md).

---

# Debug with logs and traces

Source: https://botpress.com/docs/adk-v2/testing/debugging

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

import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Traces view in Dev Console" class="block dark:hidden" src={tracesViewImg} />
  <Picture alt="Traces view in Dev Console" class="hidden dark:block" src={tracesViewDarkImg} />
</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>
  <Picture alt="Logs view in Dev Console" class="block dark:hidden" src={logsViewImg} />
  <Picture alt="Logs view in Dev Console" class="hidden dark:block" src={logsViewDarkImg} />
</Frame>

### CLI

You can also read logs from the command line:

```bash
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](/adk-v2/cli/cli-reference.md#adk-logs) for all flags.

The Dev Console Logs tab and `adk logs` read from the local log store at `.adk/bot/logs/logs.db`. `adk dev` also writes session `.log` files under `.adk/logs/` for durable troubleshooting.

## Export to your own tools

To send runtime traces to your own observability stack, start the dev server with OTLP export:

```bash
adk dev --otlp                   # export to an OpenTelemetry collector on port 4318
adk dev --otlp --port-otlp 4319  # use a different collector port (Jaeger, otel-tui, etc.)
```

## Understand behavior over time

Traces and logs show individual runs. To see aggregate trends, such as conversation volume, latency, token usage, and cost, use [Analytics](/adk-v2/testing/analytics.md).

## Common errors

| Error                              | Cause                                                  | Fix                                                                                 |
| ---------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `NO_DEV_BOT`                       | You ran a dev command before your dev bot existed      | Run `adk dev` first to create it                                                    |
| `BOT_NOT_LINKED`                   | No production bot is linked                             | Run `adk link`                                                                      |
| Deploy blocked on a dependency     | An enabled integration is unconfigured or unconnected  | Run `adk integrations status --target prod`, then configure or connect it           |
| A teammate's integration is missing | Integration state isn't shared through git            | Seed your dev bot: `adk integrations copy --from prod --to dev`                     |

---

# Run scripts

Source: https://botpress.com/docs/adk-v2/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
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
// 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
adk run scripts/process.ts order-123
adk run scripts/process.ts -- --limit 100 --verbose
```

```typescript
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
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

---

# Analytics

Source: https://botpress.com/docs/adk-v2/testing/analytics

Understand how your agent behaves over time with built-in and custom charts.

import Frame from '@/components/Frame.astro'

Traces and logs show you individual runs. Analytics shows you the bigger picture: how your agent behaves over time. It's a page in the Dev Console, which you can open from anywhere with `adk dashboard`.

## Built-in analytics

The Analytics page comes with charts that cover the metrics most agents care about:

- Conversation, message, and user volume
- Workflow volume and duration
- LLM activity and token usage
- Latency, throughput, and cost

These give you a quick read on usage and performance without leaving the ADK.

<Frame>
  <Picture alt="Built-in analytics dashboard in the Dev Console" src={analyticsBuiltinImg} />
</Frame>

## Custom analytics

Different agents are judged by different numbers. Custom Analytics lets you build your own charts from the metrics that matter to a specific agent, so a bot measured by workflow duration and one measured by escalation rate can each show what's relevant instead of the same default dashboard.

<Frame>
  <Picture alt="Building a custom analytics chart in the Dev Console" src={analyticsCustomImg} />
</Frame>

---

# Agent Map

Source: https://botpress.com/docs/adk-v2/testing/agent-map

Visualize how your agent's actions, workflows, triggers, and conversations connect.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

Agent Map is a graph view of your agent in the Dev Console. It shows your Actions, Workflows, Triggers, and Conversations, and how they reference each other.

<Frame>
  <Picture alt="Agent Map graph view in the Dev Console" class="block dark:hidden" src={agentMapImg} />
  <Picture alt="Agent Map graph view in the Dev Console" class="hidden dark:block" src={agentMapDarkImg} />
</Frame>

Agent Map is built from your project's source structure, not from a single run. It's useful for seeing how an agent is designed before you start tracing any one execution path, which helps as a project grows and the connections get harder to hold in your head.

In local development, Agent Map streams live from your project. For deployed bots, the ADK publishes the map's metadata during `adk deploy`, so the Dev Console can show a production snapshot when that metadata is available.

<Note>Agent Map is experimental. It's a best-effort view compiled by parsing your project code, so it may be incomplete or inaccurate, and its layout and details may change.</Note>

---

# Introduction to Zai

Source: https://botpress.com/docs/adk-v2/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
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](/adk-v2/zai/extract.md)        |
| `check()`     | Verify a Boolean condition                  | [Classify, validate and filter](/adk-v2/zai/classify.md) |
| `label()`     | Categorize content with multiple labels     | [Classify, validate and filter](/adk-v2/zai/classify.md) |
| `filter()`    | Filter an array by a condition              | [Classify, validate and filter](/adk-v2/zai/classify.md) |
| `sort()`      | Sort items using natural language criteria  | [Classify, validate and filter](/adk-v2/zai/classify.md) |
| `rate()`      | Rate items on a 1-5 scale                   | [Classify, validate and filter](/adk-v2/zai/classify.md) |
| `group()`     | Group items into categories                 | [Classify, validate and filter](/adk-v2/zai/classify.md) |
| `text()`      | Generate text from a prompt                 | [Generate text and summaries](/adk-v2/zai/generate.md)   |
| `rewrite()`   | Transform text based on instructions        | [Generate text and summaries](/adk-v2/zai/generate.md)   |
| `summarize()` | Summarize long content                      | [Generate text and summaries](/adk-v2/zai/generate.md)   |
| `answer()`    | Answer questions with citations             | [Generate text and summaries](/adk-v2/zai/generate.md)   |
| `patch()`     | Make surgical edits to files                | [Generate text and summaries](/adk-v2/zai/generate.md)   |

## Quick example

```typescript
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
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**.

---

# Extract structured data

Source: https://botpress.com/docs/adk-v2/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
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
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().describe('Customer email address'),
    }),
    items: z.array(
      z.object({
        name: z.string(),
        quantity: z.number(),
        unitPrice: z.number().describe('Price per unit in USD'),
      })
    ),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      state: z.string().describe('Two-letter US state code'),
      zip: z.string().describe('5-digit ZIP code'),
    }),
  })
)
```

## Example: classifying emails

`extract()` works anywhere in your agent. Here it's used inside a workflow step to parse and classify incoming emails:

```typescript
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-v2/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
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` | Maximum tokens to generate |

## Rewrite text

`zai.rewrite()` transforms text based on instructions:

```typescript
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
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
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
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')
```

---

# Classify, validate and filter

Source: https://botpress.com/docs/adk-v2/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
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
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
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
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
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
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
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
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
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                                                 |

---

# Building with Agent(0)

Source: https://botpress.com/docs/adk-v2/ai-native/agent0

Build, debug, and run your bot with Agent(0), the ADK-aware assistant in the Dev Console.

import Frame from '@/components/Frame.astro'

Agent(0) is an ADK-aware assistant built into the Dev Console. It isn't a generic chat sidebar: it understands the project you're working in and helps with the real ADK development loop.

<Frame>
  <Picture alt="Agent(0) panel in the Dev Console" class="block dark:hidden" src={agent0Img} />
  <Picture alt="Agent(0) panel in the Dev Console" class="hidden dark:block" src={agent0DarkImg} />
</Frame>

Agent(0) can:

- Edit your actions and workflows
- Run CLI commands
- Debug build and runtime errors
- Send test messages to your bot
- Inspect traces and read logs
- Pull in the integrations your project needs

## Project capabilities

Agent(0)'s project capabilities live with your project, in `.agent0/capabilities`, while its core harness behavior stays part of the ADK. Because these capabilities are part of the repo, you can customize how Agent(0) works in a specific project, and your whole team shares that setup through version control.

---

# Skills

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

Give AI coding assistants like Claude Code, Cursor, and Codex deep ADK knowledge.

Skills are packaged instructions and documentation that teach AI coding assistants how to build with the ADK. They're separate from [Agent(0)](/adk-v2/ai-native/agent0.md), the assistant built into the Dev Console: skills are for the external assistant you already code with, like Claude Code, Cursor, or Codex.

Once installed, the assistant uses them automatically when you ask it to build features, debug issues, write evals, or connect integrations. `adk init` installs them alongside your dependencies, so most projects get them out of the box.

## Install

In Claude Code, install the plugin to get every skill and its slash commands:

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

For Claude Code, Cursor, or Codex, install with the skills CLI:

```bash
npx skills add botpress/skills -s '*' -a codex claude-code -y
```

Use `bunx` instead of `npx` if your project uses Bun. To install a single skill, pass `--skill <name>` (for example, `--skill adk`).

## Available skills

| Skill                  | What it teaches                                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| **`adk`**              | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration  |
| **`adk-debugger`**     | Trace reading, log analysis, common failure diagnosis, and the debug loop                                      |
| **`adk-evals`**        | Eval file format, assertion types, CLI usage, and per-primitive testing patterns                               |
| **`adk-frontend`**     | Authentication, type generation, client setup, and calling bot actions from React/Next.js                      |
| **`adk-integrations`** | Discovering, adding, configuring, and using integrations                                                       |
| **`adk-dev-console`**  | What each Dev Console tab shows, and how to read Agent Steps, traces, and other UI                             |
| **`adk-docs`**         | Creating, reviewing, updating, and searching project documentation                                             |

## Slash commands

In Claude Code, type a command instead of describing what you need:

| Command            | What it does                                              |
| ------------------ | --------------------------------------------------------- |
| `/adk-init`        | Scaffold a new ADK project                                |
| `/adk-build`       | Interview you about a new primitive or feature, then build it |
| `/adk-test`        | Invoke a primitive end-to-end with realistic input        |
| `/adk-validate`    | Validate a primitive or a feature                         |
| `/adk-debug`       | Debug bot issues using traces and logs                    |
| `/adk-eval`        | Write, run, or debug evals                                |
| `/adk-integration` | Discover, add, and configure integrations                 |
| `/adk-frontend`    | Build a frontend that integrates with a bot               |
| `/adk-dev-console` | Explain Dev Console features and UI                       |
| `/adk-explain`     | Explain a bot's architecture, flow, and components        |
| `/adk-document`    | Create, review, update, sync, or search project docs      |
| `/adk-ship`        | Run pre-flight checks and deploy to production            |

---

# Human-in-the-loop (HITL)

Source: https://botpress.com/docs/adk-v2/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](/adk-v2/advanced/desk-hitl.md).
</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 from the CLI:

```bash
adk integrations add hitl
adk plugins add hitl
```

The plugin wires itself to the HITL integration automatically. If your project has more than one HITL-capable integration, point the plugin at the one to use with `--dep <interface>=<integrationAlias>`:

```bash
adk plugins add hitl --dep hitl=hitl
```

Set plugin-wide behavior with `adk plugins configure hitl --set <key>=<value>`, and connect the integration to your helpdesk from the Dev Console. Dependencies and their configuration live in Botpress Cloud, not in your project files. See [Managing dependencies](/adk-v2/setup/managing-dependencies.md).

## Start a handoff

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

```typescript
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 use Zendesk instead of the generic HITL integration, add it and point the plugin at it:

```bash
adk integrations add zendesk
adk plugins configure hitl --map hitl=zendesk
```

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](/adk-v2/cli/cli-reference.md#adk-deploy) for all deploy flags:

```bash
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>

---

# HITL with Desk

Source: https://botpress.com/docs/adk-v2/advanced/desk-hitl

Escalate conversations to support agents in Botpress Desk.

import { Warning } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'

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>
  <Picture alt="Botpress Desk main inbox view" class="block dark:hidden" src={deskUiImg} />
  <Picture alt="Botpress Desk main inbox view" class="hidden dark:block" src={deskUiDarkImg} />
</Frame>

## Add `desk-hitl` to your agent

Add the plugin from the CLI:

```bash
adk plugins add desk-hitl
```

### Customize handoff messages

The plugin sends default messages when an agent joins or a session ends. Override them with `adk plugins configure`, or edit them in the Dev Console:

```bash
adk plugins configure desk-hitl \
  --set agentAssignedMessage="A support agent has joined the conversation." \
  --set sessionEndedMessage="The support session has ended. Is there anything else I can help you with?"
```

Plugin configuration lives in Botpress Cloud, not in your project files. See [Managing dependencies](/adk-v2/setup/managing-dependencies.md).

## 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**](/desk/introduction.md).</Step>
  <Step>Go to **AI Agents → Deflecting Bots**.</Step>
  <Step>Add your bot.</Step>
</Steps>

<Frame>
  <Picture alt="Deflecting Bots page in Botpress Desk settings" class="block dark:hidden" src={deflectingImg} />
  <Picture alt="Deflecting Bots page in Botpress Desk settings" class="hidden dark:block" src={deflectingDarkImg} />
</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
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
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],
    })
  },
})
```

---

# CLI reference

Source: https://botpress.com/docs/adk-v2/cli/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 the flags on a specific command.

## Common tasks

| You want to…                 | Command                                              |
| ---------------------------- | ---------------------------------------------------- |
| See or switch your account   | `adk profiles list` · `adk profiles set <name>`      |
| Use a different account once | `adk <command> --profile <name>`                     |
| Link to a production bot     | `adk link`                                           |
| Develop against your dev bot | `adk dev`                                            |
| Chat with your agent         | `adk chat`                                           |
| Ship to production           | `adk deploy`                                         |
| Add an integration           | `adk integrations add <name>`                        |
| Configure it                 | `adk integrations configure <alias> --set key=value` |
| Promote dev to prod          | `adk integrations copy --from dev --to prod`         |
| Open the Dev Console         | `adk dashboard` (or bare `adk`)                      |
| Share or move a project      | `adk export` then `adk import`                       |
| Upgrade a 1.x project        | `adk project upgrade`                                |

## Global flags

These 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` (or `--format text`) for machine-readable output. A few interactive commands don't: `dev`, `login`, `profiles`, `self-upgrade`, `telemetry`, `theme`, `run`, and `assets pull`.

## Project

| Command               | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `adk init [name]`     | Scaffold a new project                                   |
| `adk dev`             | Start development mode with hot reloading                |
| `adk build`           | Build the agent for production                           |
| `adk check`           | Validate project structure, config, and primitives        |
| `adk status`          | Show project status, integrations, and server state       |
| `adk link`            | Link the project to a workspace and bot                  |
| `adk deploy`          | Deploy the agent to production                           |
| `adk project upgrade` | Apply ADK compatibility updates to a 1.x project          |

### `adk init`

```bash
adk init my-agent
```

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

### `adk dev`

Runs your agent locally against your development bot and starts the Dev Console.

```bash
adk dev
```

| Flag                    | Description                                               |
| ----------------------- | -------------------------------------------------------- |
| `-p, --port <port>`     | Development server port (default: `3000`)                |
| `--port-console <port>` | Dev Console port (default: `3001`)                       |
| `--otlp`                | Export traces to an OTLP collector (default port `4318`) |
| `--port-otlp <port>`    | OTLP collector port (Jaeger, otel-tui, etc.)             |
| `--no-watch`            | Disable file watching and hot reload                     |
| `--non-interactive`     | Emit structured NDJSON events instead of the status panel |
| `-v, --verbose`         | Show additional details                                  |

### `adk deploy`

Ships code and config to your production bot.

```bash
adk deploy
```

| Flag                        | Description                                                             |
| --------------------------- | ----------------------------------------------------------------------- |
| `-e, --env <environment>`   | Deployment environment (default: `production`)                          |
| `-y, --yes`                 | Auto-approve preflight changes without prompting                        |
| `--dry-run`                 | Compute the deploy plan without applying changes                        |
| `--confirm-storage-changes` | Confirm destructive storage changes (table/KB/asset deletions)          |
| `--allow-unconfigured`      | Deploy even if enabled dependencies are unconfigured (ships them inert)  |

### `adk link`

Points the project at a production bot and writes `agent.json`. See [Project setup](/adk-v2/setup/project-setup.md).

```bash
adk link --workspace <id> --bot <id>
```

| Flag               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `--workspace <id>` | Workspace ID                                       |
| `--bot <id>`       | Production bot ID                                  |
| `--dev <devBotId>` | Also record a development bot ID                   |
| `--api-url <url>`  | Botpress API URL                                   |
| `--local`          | Write the whole link to `agent.local.json` instead |
| `-f, --force`      | Overwrite an existing `agent.json`                 |

## Dependencies

Integrations, plugins, and interfaces are Cloud-first: these commands read and write your bot's Cloud state. They default to your development bot; pass `--target prod` to act on production. See [Managing dependencies](/adk-v2/setup/managing-dependencies.md).

### `adk integrations`

| Command                              | Description                                            |
| ------------------------------------ | ------------------------------------------------------ |
| `adk integrations add <name>`        | Add an integration (e.g. `slack` or `slack@1.4.2`)     |
| `adk integrations remove <alias>`    | Remove an integration                                  |
| `adk integrations upgrade <alias>`   | Upgrade an integration (`--to <version>`)              |
| `adk integrations enable <alias>`    | Enable an integration                                  |
| `adk integrations disable <alias>`   | Disable an integration                                 |
| `adk integrations configure <alias>` | Set config values (`--set k=v`, `--unset k`)           |
| `adk integrations list`              | List installed integrations (`--verbose` for config)   |
| `adk integrations status`            | Show each integration's capability state + remediation |
| `adk integrations info <name>`       | Show registry details for an integration               |
| `adk integrations search [query]`    | Search the registry (`--interface <name>` to filter)   |
| `adk integrations copy`              | Copy state between envs (`--from`, `--to`)             |
| `adk integrations diff`              | Show dependency state differences                      |

Common flags: `--target dev|prod`, `--alias <alias>`, and `--config key=value` (repeatable) on `add`.

```bash
adk integrations add stripe@1.4.2
adk integrations configure stripe --set apiKey=sk-...
adk integrations copy --from dev --to prod --dry-run
```

### `adk plugins`

`adk plugins` mirrors the full integration verb set (`add`, `remove`, `upgrade`, `enable`, `disable`, `configure`, `list`, `status`, `info`, `search`, `copy`, `diff`) and adds interface wiring:

| Flag                | Description                                                        |
| ------------------- | ----------------------------------------------------------------- |
| `--dep iface=alias` | On `add`: wire an interface dependency to an integration alias (repeatable) |
| `--map iface=alias` | On `configure`: rewire an interface dependency                    |

```bash
adk plugins add hitl --dep hitl=hitl
adk plugins configure hitl --map hitl=zendesk
```

### `adk interfaces`

Interfaces are read-only, so you can only inspect them:

| Command                      | Description                                 |
| ---------------------------- | ------------------------------------------- |
| `adk interfaces list`        | List built-in interfaces                    |
| `adk interfaces info <name>` | Show details for an interface (e.g. `llm`)  |

### `adk dependencies`

Portable dependency snapshots, separate from the generated `.adk/dependencies/` cache:

| Command                            | Description                                                        |
| ---------------------------------- | ----------------------------------------------------------------- |
| `adk dependencies export [output]` | Export integration and plugin state to a JSON file (`--no-config`) |
| `adk dependencies import <file>`   | Import a snapshot into an environment (`--dry-run`, `--yes`)       |

## Project portability

| Command                            | Description                                                       |
| ---------------------------------- | ----------------------------------------------------------------- |
| `adk export [output]`              | Bundle the project into a portable `.adk` archive (`--no-config`)  |
| `adk import <archive> [directory]` | Restore an archive into a new directory and link or create bots    |

## Dev processes

| Command                 | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `adk dashboard`         | Open the Dev Console, or print its address (`--no-browser`, `--format json`)               |
| `adk ps`                | List running ADK dev processes (`--wide`, `--watch [seconds]`, `--cloud`)                   |
| `adk kill [targets...]` | Stop running dev agents (`--all`, `--current`, `--dry-run`)                                |
| `adk home`              | Open the Dev Console landing screen (also runs when you call bare `adk` outside a project)  |

## Configuration and secrets

All of these accept `--prod` to target production instead of dev. See [Configuration](/adk-v2/setup/configuration.md).

| Command                        | Description                               |
| ------------------------------ | ----------------------------------------- |
| `adk config`                   | Validate and fill missing config values    |
| `adk config:get <key>`         | Read a config value                       |
| `adk config:set <key> <value>` | Set a config 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 models for the current bot  |

## Chat and testing

| Command            | Description                              |
| ------------------ | ---------------------------------------- |
| `adk chat`         | Chat with your agent in development mode  |
| `adk evals [name]` | Run eval suites                          |
| `adk evals runs`   | List or show eval run history            |

### `adk chat`

| Flag                     | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `--single <message>`     | Send one message, print the response, and exit  |
| `--conversation-id <id>` | Continue a conversation                        |
| `--timeout <duration>`   | Max wait duration (default: `60s`)             |

### `adk evals`

```bash
adk evals --tag smoke
```

| Flag                    | Description                                  |
| ----------------------- | -------------------------------------------- |
| `--tag <tag>`           | Run only evals with this tag                 |
| `--type <type>`         | Run only `capability` or `regression` evals  |
| `--judge-model <model>` | Model for `llm_judge` assertions             |
| `--prod`                | Run against the production bot               |
| `-v, --verbose`         | Show full details, not just failures         |
| `--server <url>`        | Dev server URL (auto-starts if not running)  |

`adk evals runs [runId]` lists past runs; add `--latest` for the most recent, or `--limit <n>` (default `10`).

## Logs, traces, and conversations

| Command                       | Description                                       |
| ----------------------------- | ------------------------------------------------- |
| `adk logs [tokens...]`        | Query dev server logs from `.adk/logs/`            |
| `adk traces [tokens...]`      | Query trace data from the local store              |
| `adk conversations list`      | List recent conversations                          |
| `adk conversations show <id>` | Show a conversation timeline (`--include-llm`)     |
| `adk run <script> [args...]`  | Run a TypeScript script with the full ADK runtime  |

### `adk logs`

Positional tokens filter the output: a level (`error`, `warning`, `info`), `since=<duration>`, and `limit=<n>`.

```bash
adk logs error since=1h
adk logs --follow
```

### `adk traces`

Tokens: `error`, `workflow=<name>`, `action=<name>`, `trace=<id>`, `since=<duration>`, `limit=<n>`. Add `--include-llm` to include LLM instructions, code, and tools.

### `adk run`

Runs a script from `scripts/` against your dev bot. Pass `--prod` to use the production bot, and `-f, --force` to regenerate the bot project first.

## Workflows

| Command                              | Description                              |
| ------------------------------------ | ---------------------------------------- |
| `adk workflows`                      | List discovered workflows                |
| `adk workflows inspect <name>`       | Inspect a workflow's schema and metadata |
| `adk workflows run <name> [payload]` | Run a workflow (`--wait`, `--timeout`)   |
| `adk workflows runs [id]`            | List workflow runs, or show one by ID    |

## Knowledge and assets

| Command             | Description                                         |
| ------------------- | --------------------------------------------------- |
| `adk kb sync`       | Sync knowledge bases (requires `--dev` or `--prod`)  |
| `adk assets sync`   | Sync assets with remote storage                     |
| `adk assets list`   | List asset files (`--local`, `--remote`)            |
| `adk assets status` | Show asset sync status                              |
| `adk assets pull`   | Download remote assets to the local directory        |

`adk kb sync` also accepts `--dry-run`, `-y/--yes`, `--confirm-storage-changes`, and `--force`.

## AI assistants

| Command              | Description                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `adk agent0 upgrade` | Create or update the project's [Agent(0)](/adk-v2/ai-native/agent0.md) capability bundle         |
| `adk ai-upgrade`     | Update ADK [skills](/adk-v2/ai-native/skills.md) and slash commands for external coding agents   |

## Account

| Command                      | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| `adk login`                  | Authenticate with your Botpress account                |
| `adk logout`                 | Remove credentials for the current or named profile     |
| `adk profiles list`          | List configured profiles                               |
| `adk profiles set [profile]` | Switch to a different profile                          |
| `adk self-upgrade [version]` | Upgrade the ADK CLI (alias: `self-update`)             |
| `adk telemetry`              | Manage telemetry (`--status`, `--enable`, `--disable`) |
| `adk theme`                  | Set the CLI theme (`--set dark\|light\|system`)         |

### `adk login`

```bash
adk login                       # interactive
adk login --profile work        # save under a named profile
adk login --token <token>       # non-interactive (also reads $BOTPRESS_TOKEN)
```

Delete a profile with `adk logout --profile <name>`. See [Profiles](/adk-v2/setup/profiles.md).

---

# 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](/studio/get-started/quick-start.md), 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](/studio/introduction.md) 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!

---

# 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>
  <Picture alt="Instructions" class="block dark:hidden" src={instructionsImg} />
  <Picture alt="Instructions" class="hidden dark:block" src={instructionsDarkImg} />
</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
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>
  <Picture alt="Test prompt" class="block dark:hidden" src={testPromptImg} />
  <Picture alt="Test prompt" class="hidden dark:block" src={testPromptDarkImg} />
</Frame>

Nice! The bot followed our instructions.

---

# 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>
  <Picture alt="Question" class="block dark:hidden" src={questionImg} />
  <Picture alt="Question" class="hidden dark:block" src={questionDarkImg} />
</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
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>
  <Picture alt="Question with Knowledge Base" class="block dark:hidden" src={questionWithKbImg} />
  <Picture alt="Question with Knowledge Base" class="hidden dark:block" src={questionWithKbDarkImg} />
</Frame>

Much better! The bot was able to answer the question correctly.

---

# 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>
  <Picture alt="Main Workflow" class="block dark:hidden" src={mainWorkflowImg} />
  <Picture alt="Main Workflow" class="hidden dark:block" src={mainWorkflowDarkImg} />
</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>
  <Picture alt="Transition" class="block dark:hidden" src={transitionImg} />
  <Picture alt="Transition" class="hidden dark:block" src={transitionDarkImg} />
</Frame>

This is a _transition_. It tells your bot:

> When the conversation starts, go directly to the Autonomous Node.

---

# 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>
  <Picture alt="New Standard Node" class="block dark:hidden" src={standardNodeImg} />
  <Picture alt="New Standard Node" class="hidden dark:block" src={standardNodeDarkImg} />
</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>

---

# 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>
  <Picture alt="Card" class="block dark:hidden" src={cardImg} />
  <Picture alt="Card" class="hidden dark:block" src={cardDarkImg} />
</Frame>

Notice that adding a Card opens the **Inspector** on the right side of the Studio:

<Frame>
  <Picture alt="Card inspector" class="block dark:hidden" src={cardInspectorImg} />
  <Picture alt="Card inspector" class="hidden dark:block" src={cardInspectorDarkImg} />
</Frame>

Let's add our greeting. In the **Message to send** field, paste the following:

```txt
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>
  <Picture alt="Custom greeting test" class="block dark:hidden" src={customGreetingTestImg} />
  <Picture alt="Custom greeting test" class="hidden dark:block" src={customGreetingTestDarkImg} />
</Frame>

Nice! The bot now displays a custom greeting with the opening hours.

---

# 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>
  <Picture alt="Connected Nodes" class="block dark:hidden" src={connectedNodesImg} />
  <Picture alt="Connected Nodes" class="hidden dark:block" src={connectedNodesDarkImg} />
</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>
  <Picture alt="Custom logic with AI" class="block dark:hidden" src={customLogicWithAiImg} />
  <Picture alt="Custom logic with AI" class="hidden dark:block" src={customLogicWithAiDarkImg} />
</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>

---

# 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>
  <Picture alt="Variable section" class="block dark:hidden" src={variableSectionImg} />
  <Picture alt="Variable section" class="hidden dark:block" src={variableSectionDarkImg} />
</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>
  <Picture alt="Variable" class="block dark:hidden" src={newVariableImg} />
  <Picture alt="Variable" class="hidden dark:block" src={newVariableDarkImg} />
</Frame>

---

# 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>
  <Picture alt="Autonomous Node inspector" class="block dark:hidden" src={inspectorImg} />
  <Picture alt="Autonomous Node inspector" class="hidden dark:block" src={inspectorDarkImg} />
</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>
  <Picture alt="Variable access" class="block dark:hidden" src={variableAccessImg} />
  <Picture alt="Variable access" class="hidden dark:block" src={variableAccessDarkImg} />
</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
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>
  <Picture alt="Variable test" class="block dark:hidden" src={variableTestImg} />
  <Picture alt="Variable test" class="hidden dark:block" src={variableTestDarkImg} />
</Frame>

Nice! Our modified prompt worked. If you look back at the Variables section, you can see that the value updated:

<Frame>
  <Picture alt="New value" class="block dark:hidden" src={newValueImg} />
  <Picture alt="New value" class="hidden dark:block" src={newValueDarkImg} />
</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>
  <Picture alt="New conversation" class="block dark:hidden" src={newConversationImg} />
  <Picture alt="New conversation" class="hidden dark:block" src={newConversationDarkImg} />
</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>
  <Picture alt="Variable test" class="block dark:hidden" src={variableTestImg} />
  <Picture alt="Variable test" class="hidden dark:block" src={variableTestDarkImg} />
</Frame>

Then, select <Icon icon="rotate-ccw"/> to restart the conversation and send a message:

<Frame>
  <Picture alt="User variable test" class="block dark:hidden" src={userVariableTestImg} />
  <Picture alt="User variable test" class="hidden dark:block" src={userVariableTestDarkImg} />
</Frame>

Much better! The bot remembered the name from our previous conversation. Notice that in the Variables section, the value stayed the same:

<Frame>
  <Picture alt="User variable" class="block dark:hidden" src={userVariableImg} />
  <Picture alt="User variable" class="hidden dark:block" src={userVariableDarkImg} />
</Frame>

---

# Introduction

Source: https://botpress.com/docs/api-reference

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

{/* TODO update the hub link to the new one */}
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](/api-reference/chat-api/introduction.md).

## 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](/api-reference/admin-api/getting-started.md).

## 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](/api-reference/files-api/getting-started.md).

## 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](/api-reference/tables-api/getting-started.md).

## 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](/api-reference/authentication.md#1-personal-access-token-pat) to act as either a bot or an integration). For more details, refer to the [Runtime API documentation](/api-reference/runtime-api/getting-started.md).

---

# 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](/api-reference/chat-api/introduction.md) and [Webchat documentation](/webchat/get-started/introduction.md).
</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](/api-reference/runtime-api/getting-started.md), [tables API](/api-reference/tables-api/getting-started.md), and [files API](/api-reference/files-api/getting-started.md) 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](/api-reference/runtime-api/getting-started.md) and [files API](/api-reference/files-api/getting-started.md) 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
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
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.

---

# 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
{
  "data": [...],
  "meta": {
    "nextToken": "wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g="
  }
}
```

The next request would look like this:

```http
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
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
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
{
  "type": "RateLimited",
  "description": "The request has been rate-limited.",
  "status": 429
}
```

### Example Headers

```http
RateLimit-Limit: 100
RateLimit-Remaining: 9
RateLimit-Reset: 6
```

When using the official Botpress Client, the rate limiter is automatically handled for you.

---

# 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
{
  "type": "Unknown",
  "description": "An unknown error occurred",
  "status": 500
}
```

**Payload Too Large**

```json
{
  "type": "PayloadTooLarge",
  "description": "The request payload is too large.",
  "status": 413
}
```

---

# Chat API Introduction

Source: https://botpress.com/docs/api-reference/chat-api/introduction

import { Note, Warning } from '@/components/callouts'

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](/webchat/get-started/introduction.md), 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

{/* TODO(driftable): This hub link is subject to changes and should be autogenerated */}
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:

<Picture alt="Webhook ID in the Chat Integration configuration page" src={webhookIdImg} />

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`](/api-reference/chat-api/openapi/createUser.md) 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`](/api-reference/chat-api/openapi/createConversation.md) operation. You will need to provide a user key to authenticate yourself.

6. Send a message to your bot by calling the [`createMessage`](/api-reference/chat-api/openapi/createMessage.md) 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`](/api-reference/chat-api/openapi/listMessages.md) 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:

1. 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
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`](/api-reference/chat-api/openapi/createUser.md) will result in an error response. When needed, call [getOrCreateUser](/api-reference/chat-api/openapi/getOrCreateUser.md) 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`](/api-reference/chat-api/openapi/listenConversation.md) 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 1 MB.

---

# 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
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
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
{
  "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
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>

{/* TODO(driftable): This script is subject to changes and should be autogenerated */}

```ts
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 50 MB.

## 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)

---

# 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/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](/api-reference/authentication.md) 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
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 title="npm"
npm install @botpress/client
```

```bash title="pnpm"
pnpm install @botpress/client
```

```bash title="yarn"
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>

{/* TODO(driftable): This script is subject to changes and should be autogenerated */}

```ts
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](/api-reference/files-api/how-tos/manage-files.md#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       | 1 MB                                                                                             |
| Rate limits                | [Same as all other endpoints](/studio/guides/advanced/safety/preventing-abuse.md) 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
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](/api-reference/files-api/openapi/upsertFile.md#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
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
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 title="npm"
npm install @botpress/client
```

```bash title="pnpm"
pnpm install @botpress/client
```

```bash title="yarn"
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
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
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](/studio/concepts/knowledge-base/introduction.md), 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 title="Using the Botpress client" {10-14}
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 title="Using an HTTP request" {17-21}
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
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
const file = await client.uploadFile({
  key: 'test.txt',
  content: 'This is a file accessible by all integrations of the bot',
  accessPolicies: ['integrations'],
})

const fileUrl = 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
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
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](/api-reference/files-api/how-tos/manage-files.md#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 title="Using the Botpress Client"
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 title="Calling the API directly"
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
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.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](/api-reference/files-api/how-tos/manage-files.md#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 title="Using the Botpress Client"
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 title="Calling the API directly"
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](/api-reference/files-api/how-tos/manage-files.md#listing-existing-files-of-a-bot) API endpoint.

<CodeGroup>

```ts title="Using the Botpress Client"
const res = await client.listFiles({})
const files = res.files
```

```ts title="Calling the API directly"
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 title="Using the Botpress Client"
const { files } = await client.listFiles({
  tags: {
    category: 'Sales',
  },
})
```

```ts title="Calling the API directly"
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 title="Using the Botpress Client"
const { files } = await client.listFiles({
  tags: {
    category: ['Sales', 'Marketing'],
  },
})
```

```ts title="Calling the API directly"
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 title="Using the Botpress Client"
const { files } = await client.listFiles({
  tags: {
    integrationName: {
      exists: false,
    },
  },
})
```

```ts title="Calling the API directly"
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 title="Using the Botpress Client"
const { files } = await client.listFiles({
  tags: {
    integrationName: {
      not: 'webchat', // Could be a string or an array of strings
    },
  },
})
```

```ts title="Calling the API directly"
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 title="Using the Botpress Client"
const { files } = await client.listFiles({
  tags: {
    integrationName: {
      in: ['webchat', 'whatsapp'], // Could be a string or an array of strings
    },
  },
})
```

```ts title="Calling the API directly"
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](/api-reference/files-api/how-tos/manage-files.md#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
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 title="Using the Botpress Client"
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 title="Calling the API directly"
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 title="Using the Botpress Client"
await client.deleteFile({ id: 'YOUR_FILE_ID' })
```

```ts title="Calling the API directly"
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>

---

# 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
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 title="npm"
npm install @botpress/client
```

```bash title="pnpm"
pnpm install @botpress/client
```

```bash title="yarn"
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>

{/* TODO(driftable): This script is subject to changes and should be autogenerated */}

```ts
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 40 MB.

---

# 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 title="npm"
npm install @botpress/client
```

```bash title="pnpm"
pnpm install @botpress/client
```

```bash title="yarn"
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>

{/* TODO(driftable): This script is subject to changes and should be autogenerated */}

```ts
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 1 MB.

## 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/listConversations).

---

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

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

```ts
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:

{/* TODO(driftable): This list is subject to changes and should be autogenerated */}

- **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:

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

```ts
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:

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

```ts
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:

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

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

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

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

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

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

{/* TODO(driftable): This type is subject to changes and should be autogenerated */}

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

{/* TODO: say something about Bot and Workflow Tags */}
{/* TODO: add a section about workflows */}

## 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/listConversations).

---

# Changelog

Source: https://botpress.com/docs/changelog

The latest updates and improvements to Botpress.

<ChangelogList />

---

# Botpress ADK

Source: https://botpress.com/docs/adk-v1-17

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

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

---

# HITL with Desk

Source: https://botpress.com/docs/adk-v1-17/advanced/desk-hitl

Escalate conversations to support agents in Botpress Desk.

import { Warning } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import Steps from '@/components/Steps.astro'
import Step from '@/components/Step.astro'

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>
  <Picture alt="Botpress Desk main inbox view" class="block dark:hidden" src={deskUiImg} />
  <Picture alt="Botpress Desk main inbox view" class="hidden dark:block" src={deskUiDarkImg} />
</Frame>

## Add `desk-hitl` to your agent

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

```typescript
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
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**](/desk/introduction.md).</Step>
  <Step>Go to **AI Agents → Deflecting Bots**.</Step>
  <Step>Add your bot.</Step>
</Steps>

<Frame>
  <Picture alt="Deflecting Bots page in Botpress Desk settings" class="block dark:hidden" src={deflectingImg} />
  <Picture alt="Deflecting Bots page in Botpress Desk settings" class="hidden dark:block" src={deflectingDarkImg} />
</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
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
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-v1-17/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](/adk-v1-17/advanced/desk-hitl.md).
</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
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
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
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](/adk-v1-17/cli/cli-reference.md#adk-deploy) for all deploy flags:

```bash
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-v1-17/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
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
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
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`](/adk-v1-17/cli/cli-reference.md#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-v1-17/cli/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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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-v1-17/conversations/ai-execution

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

import { Note, Tip } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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}
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 {3,8-13}
// 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}
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](/adk-v1-17/data/knowledge.md).
</Tip>

## Tools

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

```typescript highlight={6}
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](/adk-v1-17/conversations/tools.md).

## Exits

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

```typescript
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
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
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
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
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
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
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
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](/adk-v1-17/testing/debugging.md).

<Frame>
  <Picture alt="Traces view in dev console" class="block dark:hidden" src={tracesViewImg} />
  <Picture alt="Traces view in dev console" class="hidden dark:block" src={tracesViewDarkImg} />
</Frame>

---

# Use custom components

Source: https://botpress.com/docs/adk-v1-17/conversations/custom-components

Build and render custom React UI inside Webchat.

Custom components let you render your own React UI inside [Webchat](/webchat/get-started/introduction.md). 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
// 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
// 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}
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}
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}
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
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-v1-17/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}
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
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

When the expire timer fires, the framework runs this sequence:

1. **Race guard check**: did the user send a message after this expiration was scheduled? If yes, skip silently — timers are already rescheduled.
2. **Your handler runs** with `type: "expire"`.
3. **Framework cleanup** runs in order:
   1. Cancel active workflows
   2. Cancel pending nudge
   3. Set `session.status` to `expired`
   4. Tag the conversation
   5. Reset user state
   6. Clear the LLM transcript
4. **Done.** The next message 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
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
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
lifecycle: {
  nudge: { after: "10m", interval: "30m", max: 2 },
}
```

### Expiration-only (no nudges)

Silently expire after inactivity without reminders:

```typescript
lifecycle: {
  expire: { after: "1h" },
}
```

### Different timeouts per channel

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

```typescript
// 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-v1-17/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
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](/webchat/get-started/introduction.md), 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](/adk-v1-17/conversations/custom-components.md) 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
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
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
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
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
await conversation.startTyping()
await conversation.stopTyping()
```

## Conversation tags

Read and write metadata tags on the conversation:

```typescript
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](/adk-v1-17/setup/configuration.md#tags) for more information.
</Note>

## Loading a conversation by ID

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

```typescript
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
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-v1-17/conversations/setup

Handle user messages across channels.

import { Info, Tip } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import CodeGroup from '@/components/CodeGroup.astro'
import Tree from '@/components/tree/Tree.astro'
import TreeFolder from '@/components/tree/TreeFolder.astro'
import TreeFile from '@/components/tree/TreeFile.astro'

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
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>
  <Picture alt="Chat page in dev console" class="block dark:hidden" src={agentStepsImg} />
  <Picture alt="Chat page in dev console" class="hidden dark:block" src={agentStepsDarkImg} />
</Frame>

## Channel matching

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

<CodeGroup>

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

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

```ts title="Array of channels" highlight={2-5}
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
// 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:

<Tree>
  <TreeFolder name="src/conversations" defaultOpen>
    <TreeFile name="webchat.ts" comment="Webchat messages" />
    <TreeFile name="slack.ts" comment="Slack messages" />
    <TreeFile name="support.ts" comment="Support channel" />
  </TreeFolder>
</Tree>

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
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](/adk-v1-17/workflows/create.md), [lifecycle management](/adk-v1-17/conversations/lifecycle.md), 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
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}
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](/adk-v1-17/conversations/state.md).
</Tip>

---

# Manage state

Source: https://botpress.com/docs/adk-v1-17/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 {6-10,12-18}
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}
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
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
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
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
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
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
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
import { bot, user } from '@botpress/runtime'

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

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

```typescript
handler: async ({ conversation }) => {
  conversation.tags.priority = 'high'
  const priority = conversation.tags.priority
}
```

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

```typescript
const owner = conversation.tags['webchat:owner']
```

## Bot and user identity

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

```typescript
import { bot, user } from '@botpress/runtime'

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

---

# Define tools

Source: https://botpress.com/docs/adk-v1-17/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
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}
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 {6-15,19}
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
// 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
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
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}
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](/adk-v1-17/external/actions.md) 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}
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](/adk-v1-17/workflows/create.md) for more information.</Tip>

## Calling actions from tools

Tools can call actions for reusable logic:

```typescript highlight={8}
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-v1-17/data/knowledge

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

import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Knowledge page in dev console" class="block dark:hidden" src={knowledgeConsoleImg} />
  <Picture alt="Knowledge page in dev console" class="hidden dark:block" src={knowledgeConsoleDarkImg} />
</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}
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
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
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](/adk-v1-17/setup/integrations.md)).

```typescript
const DocsSource = DataSource.Website.fromWebsite('https://example.com', {
  fetch: 'integration:browser',
})
```

### Website from llms.txt

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

```typescript
const DocsSource = DataSource.Website.fromLlmsTxt('https://example.com/llms.txt')
```

### Website from specific URLs

Index a fixed list of pages:

```typescript
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
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
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](/adk-v1-17/workflows/create.md):

```typescript
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
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
await ProductDocs.refreshSource('my-source-id', { force: true })
```

---

# Tables

Source: https://botpress.com/docs/adk-v1-17/data/tables

Define and query structured data storage.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import CodeGroup from '@/components/CodeGroup.astro'

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
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>
  <Picture alt="Tables page in dev console" class="block dark:hidden" src={tablesConsoleImg} />
  <Picture alt="Tables page in dev console" class="hidden dark:block" src={tablesConsoleDarkImg} />
</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
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}
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
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
import OrderTable from '../tables/order-table'

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

### Find rows

```typescript
const { rows } = await OrderTable.findRows({
  filter: { status: 'pending' },
  orderBy: 'createdAt',
  orderDirection: 'desc',
  limit: 10,
})
```

### Get a single row

```typescript
const row = await OrderTable.getRow({ id: 42 })
```

### Update rows

```typescript
await OrderTable.updateRows({
  rows: [{ id: orders[0].id, status: 'completed' }],
})
```

### Upsert rows

Insert or update based on a key column:

```typescript
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 title="Delete rows by name"
await OrderTable.deleteRows({ status: 'cancelled' })
```

```typescript title="Delete rows by ID"
await OrderTable.deleteRowIds([1, 2, 3])
```

```typescript title="Delete all rows"
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
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
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
const { rows } = await TicketTable.findRows({
  search: 'VPN connection issues',
  limit: 10,
})
```

Combine with filters for hybrid queries:

```typescript
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
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
// 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-v1-17/external/actions

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

import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Actions page in dev console" class="block dark:hidden" src={actionsConsoleImg} />
  <Picture alt="Actions page in dev console" class="hidden dark:block" src={actionsConsoleDarkImg} />
</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}
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
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
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
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
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](/adk-v1-17/conversations/tools.md) 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}
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
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
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](/api-reference/runtime-api/getting-started.md)'s [`callAction`](/api-reference/runtime-api/openapi/callAction.md) endpoint. External services can call your agent's actions over HTTP:

```bash
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-v1-17/external/triggers

React to events from integrations and custom events.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Triggers page in dev console" class="block dark:hidden" src={triggersConsoleImg} />
  <Picture alt="Triggers page in dev console" class="hidden dark:block" src={triggersConsoleDarkImg} />
</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}
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"
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"
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}
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-v1-17/get-started/introduction

TypeScript framework for building AI agents on Botpress.

import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Botpress ADK" class="block dark:hidden" src={introNewImg} />
  <Picture alt="Botpress ADK" class="hidden dark:block" src={introNewDarkImg} />
</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
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.

---

# Quickstart

Source: https://botpress.com/docs/adk-v1-17/get-started/quickstart

Install the ADK and create your first agent project.

import { Info, Tip, Check } from '@/components/callouts'
import Frame from '@/components/Frame.astro'
import CodeGroup from '@/components/CodeGroup.astro'
import LinkCard from '@/components/LinkCard.astro'

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 title="macOS & Linux"
curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
```

```powershell title="Windows (PowerShell)"
powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
```

</CodeGroup>

Then, verify the installation:

```bash
adk --version
```

Log in to your Botpress account:

```bash
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
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
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
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>
  <Picture alt="ADK dev console" class="block dark:hidden" src={quickstartImg} />
  <Picture alt="ADK dev console" class="hidden dark:block" src={quickstartDarkImg} />
</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
adk chat
```

```txt
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
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:

<LinkCard
  href="/adk-v1-17/setup/configuration.md"
  title="Agent configuration"
  description="Project structure, models, state, and dependencies."
  icon="settings"
/>

---

# Configuration

Source: https://botpress.com/docs/adk-v1-17/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>
  <TreeFolder name="src" defaultOpen>
    <TreeFolder name="actions">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="conversations">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="knowledge">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="tables">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="triggers">
      <TreeFile name="index.ts" />
    </TreeFolder>
    <TreeFolder name="workflows">
      <TreeFile name="index.ts" />
    </TreeFolder>
  </TreeFolder>
  <TreeFolder name="evals">
    <TreeFile name="index.ts" />
  </TreeFolder>
  <TreeFile name=".mcp.json" />
  <TreeFile name="agent.config.ts" />
  <TreeFile name="agent.json" />
  <TreeFile name="agent.local.json" />
  <TreeFile name="AGENTS.md" />
  <TreeFile 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]
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
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
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
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
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](/adk-v1-17/conversations/state.md).
</Tip>

### Tags

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

```typescript
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
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](/adk-v1-17/setup/environment.md#secrets).
</Tip>

### Configuration

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

```typescript
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](/adk-v1-17/setup/environment.md#configuration).
</Tip>

### Dependencies

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

```bash
adk add webchat
adk add slack@latest
```

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

```typescript
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](/adk-v1-17/setup/integrations.md).
</Tip>

### Custom events

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

```typescript
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](/adk-v1-17/external/triggers.md).

### Evals

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

```typescript
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](/adk-v1-17/testing/evals.md).</Tip>

---

# Environment setup

Source: https://botpress.com/docs/adk-v1-17/setup/environment

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

import { Tip, Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Environment selector in dev console" class="block dark:hidden" src={environmentSelectorImg} />
  <Picture alt="Environment selector in dev console" class="hidden dark:block" src={environmentSelectorDarkImg} />
</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
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
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](/adk-v1-17/cli/cli-reference.md#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
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>
  <Picture alt="Secrets management in dev console" class="block dark:hidden" src={secretsConsoleImg} />
  <Picture alt="Secrets management in dev console" class="hidden dark:block" src={secretsConsoleDarkImg} />
</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
configuration: {
  schema: z.object({
    supportEmail: z.string().default("help@example.com"),
    maxRetries: z.number().default(3),
    enableBeta: z.boolean().default(false),
  }),
},
```

### Setting values

```bash
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>
  <Picture alt="Config variables in dev console" class="block dark:hidden" src={configVariablesConsoleImg} />
  <Picture alt="Config variables in dev console" class="hidden dark:block" src={configVariablesConsoleDarkImg} />
</Frame>

### Using configuration at runtime

```typescript
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
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-v1-17/setup/integrations

Connect your agent to channels and external services.

import { Note } from '@/components/callouts'
import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Integrations page in dev console" class="block dark:hidden" src={integrationsConsoleImg} />
  <Picture alt="Integrations page in dev console" class="hidden dark:block" src={integrationsConsoleDarkImg} />
</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>
  <Picture alt="Integration configuration in dev console" class="block dark:hidden" src={integrationConfigConsoleImg} />
  <Picture
    alt="Integration configuration in dev console"
    class="hidden dark:block"
    src={integrationConfigConsoleDarkImg}
  />
</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
dependencies: {
  integrations: {
    webchat: {
      version: "webchat@latest",
      enabled: true,
    },
  },
},
```

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

```typescript
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](/adk-v1-17/cli/cli-reference.md).
</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-v1-17/testing/agent-steps

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

import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Agent Steps panel in dev console" class="block dark:hidden" src={agentStepsImg} />
  <Picture alt="Agent Steps panel in dev console" class="hidden dark:block" src={agentStepsDarkImg} />
</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](/adk-v1-17/testing/debugging.md) for more on the Traces view.

---

# Debug with logs and traces

Source: https://botpress.com/docs/adk-v1-17/testing/debugging

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

import Frame from '@/components/Frame.astro'

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>
  <Picture alt="Traces view in dev console" class="block dark:hidden" src={tracesViewImg} />
  <Picture alt="Traces view in dev console" class="hidden dark:block" src={tracesViewDarkImg} />
</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>
  <Picture alt="Logs view in dev console" class="block dark:hidden" src={logsViewImg} />
  <Picture alt="Logs view in dev console" class="hidden dark:block" src={logsViewDarkImg} />
</Frame>

### CLI

You can also read logs from the command line:

```bash
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](/adk-v1-17/cli/cli-reference.md#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-v1-17/testing/evals

Automated conversation tests for your agent.

import Frame from '@/components/Frame.astro'

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
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
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
{
  event: {
    type: "order.placed",
    payload: { orderId: "ord-123", total: 49.99 },
  },
  assert: {
    response: [{ contains: "order" }],
  },
}
```

Assert the agent doesn't respond:

```typescript
{
  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
assert: {
  state: [
    { path: "messageCount", changed: true },
    { path: "topic", equals: "weather" },
  ],
}
```

### Tables

Assert on table data:

```typescript
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
assert: {
  workflow: [
    { name: "processOrder", entered: true },
    { name: "processOrder", completed: true },
  ],
}
```

### Timing

Assert on response time:

```typescript
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
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
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
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
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
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
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
new Eval({
  name: 'greeting',
  tags: ['smoke', 'core'],
  conversation: [
    /* ... */
  ],
})
```

```bash
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
new Eval({
  name: 'fix-for-ticket-priority-bug',
  type: 'regression',
  conversation: [
    /* ... */
  ],
})
```

```bash
adk evals --type regression    # Run only regression evals
```

## Run evals

From the CLI:

```bash
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
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>
  <Picture alt="Evals page in dev console" class="block dark:hidden" src={evalsConsoleImg} />
  <Picture alt="Evals page in dev console" class="hidden dark:block" src={evalsConsoleDarkImg} />
</Frame>

---

# Run scripts

Source: https://botpress.com/docs/adk-v1-17/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
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
// 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
adk run scripts/process.ts order-123
adk run scripts/process.ts -- --limit 100 --verbose
```

```typescript
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
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-v1-17/workflows/create

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

import Frame from '@/components/Frame.astro'

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
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>
  <Picture alt="Workflows page in dev console" class="block dark:hidden" src={workflowsConsoleImg} />
  <Picture alt="Workflows page in dev console" class="hidden dark:block" src={workflowsConsoleDarkImg} />
</Frame>

### Persistent state

Add a `state` schema to carry data across the workflow's steps and retries. State is persisted between executions:

```typescript
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
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
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
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
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
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
await instance.cancel()
```

### Set timeout

Extend or change the workflow timeout:

```typescript
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
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
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
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
export default new Workflow({
  name: 'longProcess',
  timeout: '1h',
  handler: async ({ step }) => {
    // ...
  },
})
```

For workflows that need to run longer than 5 minutes, use [steps](/adk-v1-17/workflows/steps.md). 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-v1-17/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}
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
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
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
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
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
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-v1-17/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
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
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
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
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
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
await step.listen('wait-for-payment')
```

## Fail and abort

Use `.fail()` or `.abort()` to stop execution explicitly:

```typescript
// 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
import ProcessingWorkflow from '../workflows/processing'

const result = await step.executeWorkflow('process-data', ProcessingWorkflow, { data: inputData })
```

Or wait for an already-running workflow:

```typescript
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
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
await step.forEach('notify-users', users, async (user) => await sendNotification(user), { concurrency: 10 })
```

### `batch`

Process items in sequential batches:

```typescript
await step.batch('bulk-insert', records, async (batch) => await database.bulkInsert(batch), { batchSize: 100 })
```

---

# Classify, validate and filter

Source: https://botpress.com/docs/adk-v1-17/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
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
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
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
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
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
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
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
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
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-v1-17/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
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
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
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-v1-17/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
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
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
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
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
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-v1-17/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
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](/adk-v1-17/zai/extract.md)        |
| `check()`     | Verify a Boolean condition                  | [Classify, validate and filter](/adk-v1-17/zai/classify.md) |
| `label()`     | Categorize content with multiple labels     | [Classify, validate and filter](/adk-v1-17/zai/classify.md) |
| `filter()`    | Filter an array by a condition              | [Classify, validate and filter](/adk-v1-17/zai/classify.md) |
| `sort()`      | Sort items using natural language criteria  | [Classify, validate and filter](/adk-v1-17/zai/classify.md) |
| `rate()`      | Rate items on a 1-5 scale                   | [Classify, validate and filter](/adk-v1-17/zai/classify.md) |
| `group()`     | Group items into categories                 | [Classify, validate and filter](/adk-v1-17/zai/classify.md) |
| `text()`      | Generate text from a prompt                 | [Generate text and summaries](/adk-v1-17/zai/generate.md)   |
| `rewrite()`   | Transform text based on instructions        | [Generate text and summaries](/adk-v1-17/zai/generate.md)   |
| `summarize()` | Summarize long content                      | [Generate text and summaries](/adk-v1-17/zai/generate.md)   |
| `answer()`    | Answer questions with citations             | [Generate text and summaries](/adk-v1-17/zai/generate.md)   |
| `patch()`     | Make surgical edits to files                | [Generate text and summaries](/adk-v1-17/zai/generate.md)   |

## Quick example

```typescript
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
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 cols={3}>
  <LinkCard
    href="/adk-v1-17/zai/extract.md"
    title="Extract structured data"
    description="Pull typed data from unstructured text."
    icon="braces"
  />
  <LinkCard
    href="/adk-v1-17/zai/generate.md"
    title="Generate text and summaries"
    description="Generate, rewrite, summarize, and answer with citations."
    icon="sparkles"
  />
  <LinkCard
    href="/adk-v1-17/zai/classify.md"
    title="Classify, validate and filter"
    description="Check conditions, label content, filter, sort, rate, and group."
    icon="tags"
  />
</CardGroup>

---

# Botpress ADK

Source: https://botpress.com/docs/adk-v2

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

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

---

# 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"
  cta="Contact our sales team to try Desk"
>
  Botpress Desk is currently available upon request for <Badge variant="team">Team</Badge>,{' '}
  <Badge variant="experimental">Managed</Badge>, and <Badge variant="outline">Enterprise</Badge> customers.
</Card>
<Card
  title="Read the Botpress Desk docs"
  href="https://desk.support.channel/"
  cta="Get started with the Botpress Desk documentation"
/>

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

---

# Welcome to Botpress

Source: https://botpress.com/docs

Understand the Botpress documentation and start building.

<HomePage />

---

# Generic Entities

Source: https://botpress.com/docs/integrations/sdk/interface/concepts/entities

## Overview

Entities define **standardized data structures** for an interface.

Once an interface defines entities, its actions and events can consume or produce instances of those entities. Plugins can also define a dependency on specific interfaces, then consume entities produced by integrations that implement those interfaces.

Integrations that implement an interface can:

- Rename entities to align with the terminology of external services
- Extend entities with extra fields to meet the specific needs of the external service.

## Example: `listable` interface

Consider a `listable` interface designed to provide standardized listing functionality across different services:

### Interface Definition

- Defines an `item` entity as a base structure for `listable` resources
- Specifies a `listItems` action that returns `item` results

### GitHub integration implementation

An integration connecting to GitHub might implement this interface as follows:

- Extends the `item` entity to create a `pullRequest` entity with GitHub-specific fields
- Renames the `listItems` action to `listPullRequests` to reflect GitHub terminology
- Implements the required functionality while using terminology that makes sense for GitHub

### Slack integration implementation

A Slack integration might implement the same interface differently:

- Extends the `item` entity to create a `channel` entity with Slack-specific properties
- Renames the `listItems` action to `listChannels` to reflect Slack terminology
- Provides the same core capability but adapted to Slack's specific requirements

---

# Botpress Hub

Source: https://botpress.com/docs/studio/concepts/botpress-hub

<Picture src={botpressHubImg} alt="Botpress Hub marketplace" />

[Botpress Hub](https://botpress.com/hub) is a marketplace for pre-built integrations and skills. It's a great way to get started with Botpress and to extend your bot's capabilities.

---

# Inspector

Source: https://botpress.com/docs/studio/concepts/inspector

The top right-hand side panel is the Inspector. The Inspector will display additional properties of the components you select in the main (center) panel.

## Logged-in Account

Shows the Account that you've logged in. Click on it to log-out.

## Share

Click on the Share button to share your bot with others. You can share your bot with others by sending them the link to your bot.

Make sure to hit the Publish button first to make your bot publicly available.

## Publish

Your bot will only be made publicly available (or updated) when you publish it with this one-click deployment to the cloud.

---

# Library

Source: https://botpress.com/docs/studio/concepts/library

Repository for managing global Intents and Entities, enabling the extraction and classification of messages.

<Warning>
  The Library tab is **deprecated**. Only bots that already created intents and entities will be able to use it.

For Intents, use the [AI Transition Card](/studio/concepts/cards/ai/ai-transition.md). For Entities, use the [AI Task Card](/studio/concepts/cards/ai/ai-task.md).

</Warning>

The NLU Library is a key feature within Botpress, designed to manage and organize global Intents and Entities. These components are essential for understanding and processing user input, enabling your bot responds accurately and effectively.

## Intents

Intents are the backbone of understanding in a bot. They represent the purpose or goal behind a user's message, allowing the bot to determine the appropriate response. Each intent can have multiple utterances—different ways users might express the same request.

For example, an "Ordering a coffee" intent could include utterances like:

"I want coffee"\
"I'd like some coffee, please"\
"Do you have a decaf espresso?"\
"Hi. I'd like to order a latte, please.

The bot compares user messages against these utterances to match them to the correct intent with the highest confidence score.

| User Message                                | Intent Matched | Confidence |
| :------------------------------------------ | :------------: | ---------: |
| I would like to order a coffee.             |  place-order   |       0.97 |
| An espresso, please                         |  place-order   |       0.91 |
| Can you please give me a double cappuccino? |  place-order   |       0.96 |

### Creating an Intent

To create a new intent:

1. Navigate to the Library
2. Click the + button to add a new intent
3. Provide a simple name for the intent (e.g., "order coffee")

### Adding Utterances

After creating an intent, you need to define utterances that represent different ways a user might express the same intent.

1. In the intent creation window, enter at least 10 utterances
2. Save your changes

Utterances currently support a maximum of 280 characters each.

### Inline Intents

Inline intents are specialized intents that can be defined directly on transitions within a Workflow. They function like global intents but are limited to specific scenarios within a conversation, making them ideal for context-sensitive tasks.

To use inline intents:

- Define them directly on a transition within your Workflow
- Add relevant utterances

## Entities

Entities are data points or parameters that provide additional context within an intent. They allow your bot to extract and normalize specific details from a user's message, such as a date, time, color, or any other relevant piece of information.

<Info>
Example

The place-order intent contains the following entities:

**caffeine** that specifies if the coffee is caffeinated or decaffeinated.

**size** for a single or a double shot.

**drink** that specifies the kind of drink asked for.

Attached to NLU extraction, you will find an entities property which is an array of System and Custom entities.

</Info>

### Custom Entities

Botpress provides two types of custom entities: pattern and list entities. To define a custom entity, go to the Library tab of the Explorer. From there, you can define your custom entities which will be available for any input message treated by your bot. Go ahead and click on New entity.

### Using Entities

You may access and use entity data by looking up the event.nlu.entities variable in your hooks, Workflow transitions or Execute Code cards.

### List Entities

List extraction behaves similarly to pattern extraction. However, you'll be able to add different occurrences of your entity with corresponding synonyms.

Let's take Airport Codes as an example:

Extraction will go like this: User said Type Value "Find a flight from SFO to Mumbai" "Airport Codes" ["SFO", "BOM"]

### Pattern Entities

Pattern or Regular Expression Extraction allows you to extract information presented in a format that can be described using Regular Expression (RegEx). Once you've created a pattern entity, Botpress Native NLU will perform a regex extraction on each incoming message and add it to event.nlu.entities.

Example:

Given a Pattern Entity definition with `[A-Z]\{3}-\[0-9]\{4}-[A-Z]\{3}` as a pattern: Extraction will go like this: User said Type Value Find product BHZ-1234-UYT SKU BHZ-1234-UYT

---

# Schema

Source: https://botpress.com/docs/studio/concepts/schema

You can create custom object schemas (variable types) to validate the data you are working with. This is useful when you want to ensure that the data you are working with is in the correct format.

---

# Botpress Features

Source: https://botpress.com/docs/studio/guides/advanced/additional-information/botpress-features

<Picture src={gettingStartedFeaturesImg} alt="" />

## Overall Product Specifications

<table>
  <thead>
    <tr>
      <th>
        Feature
      </th>

      <th>
        Description
      </th>
    </tr>

  </thead>

  <tbody>
    <tr>
      <td>
        SDK
      </td>

      <td>
        The utility functions that can be used as arguments in user custom code. See the [NPM package](https://www.npmjs.com/package/@botpress/sdk) and [API documentation](/api-reference.md)
      </td>
    </tr>

    <tr>
      <td>
        Security
      </td>

      <td>
        <ul><li>Audit logs for all activities in your workspace</li><li>Encryption at rest and in transit</li><li>Rate limits & various HTTP-server limits</li><li>SSO - [talk to our sales representatives](https://botpress.com/contact-us)</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        CI/CD
      </td>

      <td>
        One-click publish to production
      </td>
    </tr>

    <tr>
      <td>
        Multi-Channel Support
      </td>

      <td>
        Instantly deliver your bots on all the major messaging channels <br /><ul><li>Botpress Webchat</li><li>Facebook Messenger</li><li>Microsoft Teams</li><li>SMS via Twilio</li><li>WhatsApp</li><li>Line</li><li>Viber</li><li>Instagram</li><li>Coming Soon: Intercom, Webhook, Gmail, Rocket.Chat and more.</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Botpress Webchat
      </td>

      <td>
        <ul>**Create custom message widgets**<li>Create your own GUI messages using React</li><li>Customizable with CSS</li><br />**Flexibility for users**<li>Multiple simultaneous conversations with the same bot</li><li>Reset & delete conversation (for privacy purposes)</li><li>File-sharing using Shareable link</li><li>Hosted on AWS S3 or BPFS</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Custom Chatbot Branding
      </td>

      <td>
        [Rebrand the Botpress Webchat interface](/webchat/get-started/configure-your-webchat.md)
      </td>
    </tr>

    <tr>
      <td>
        Community Support
      </td>

      <td>
        <ul><li>[Botpress forum & community](https://discord.gg/botpress)</li><li>Intercom live support</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Multilingual Support
      </td>

      <td>
        <ul><li>Supported Languages: you can use Botpress to make bots in 100+ languages. However during the early preview of the new Botpress, only English is supported for natural language understanding.</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Conversational AI Management
      </td>

      <td>
        <ul><li>Managed Natural Language Understanding (NLU) Engine - an industrial-grade native NLU engine, from domain specific natural language to structured data</li><li>**Intent classification** - understand the type of action or out of scope conveyed in the sentences and all its participating parts (for example: book a flight, order dinner, buy a product, etc.)</li><li>**Entity extraction** - locate and classify named entities into predefined categories such as person names, organizations, locations, product SKUs, etc. Regex/pattern entities, List entities, Fuzzy matching, pre-built entities</li><li>**Slot tagging** - tag the words which carry meaning to the sentences (for example: landing city, type of meal, etc.)</li><li>**Language identification** - determining the natural language that a document or part thereof is written in (for example: English, French, etc.)</li><li>**Natural Language Understanding**: any number of languages within the same chatbot; the bot is able to detect the user's language and then answer in kind</li><li>**Spell checking** - check for misspellings and automatically fix the spelling mistakes so that the downstream NLU performs more accurately</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Built-in Content Types
      </td>

      <td>
        [Supported content types for each channel](/studio/concepts/cards/send-messages.md#message-types)
      </td>
    </tr>

    <tr>
      <td>
        Visual conversation / dialog management
      </td>

      <td>
        Visual developer interface to create and management dialog states and topic <br /><ul><li>Low-code drag and drop user interface</li><li>Multiple visual flows and subflows with conditions divided by topics</li><li>Multi-turn and the ability to jump from a topic to another seamlessly</li><li>Topic management - process that enables data elements pertaining to a specific topic to be maintained within conversations (for example: user name, SKU number, etc.)</li><li>Conversational detours - while the visual flows represent the "happy paths" that are desired by the conversation designers, detours are about automatically and gracefully handling exceptions</li><li>Template management - use pre-made templates to get started or find inspiration</li><li>Intelligent slot filling - prompting for missing form fields</li><li>Workflow management - group and reuse flows and subflows to embed and manage domain specific knowledge</li><li>Code autocompletion and user interface shortcuts</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        FAQ/Q\&A
      </td>

      <td>
        Create, manage, and centrally access the most frequently asked questions the users may have <br /><ul><li>Context management</li><li>Rich messages</li><li>Message "alternatives" - the bot doesn’t always say the same thing</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Human in the Loop (HITL)
      </td>

      <td>
        Straightforward integrations with leading third party HITL, including Salesforce, Zendesk, ServiceNow, Oracle, Intercom, Genesis, Twilio Flex, Nuance and LiveAgent.
      </td>
    </tr>

    <tr>
      <td>
        Analytics & continuous bot training
      </td>

      <td>
        Dashboards and tools to capture and improve user engagement and bot accuracy <br /><ul><li>Misunderstood - capture everything the bot doesn't understand and use it to improve your bot or expand its capabilities</li><li>Engagement</li><li>Conversations</li><li>Interactions</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Testing, debugging, and logging
      </td>

      <td>
        End-to-end conversation emulation & testing <br />NLU testing <br />Debugging tools <br />Logging
      </td>
    </tr>

    <tr>
      <td>
        Chatbot privacy
      </td>

      <td>
        <ul><li>Sensitive data / conversation obfuscation</li><li>Variable time-based deletion</li><li>Selective data persistence</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        JavaScript IDE
      </td>

      <td>
        <ul><li>Easily integrate with your internal systems and any third parties</li><li>Actions & Hooks - create and edit actions within Botpress (for example: call an API). Features typing and intelligent code completion</li><li>VS Code embedded in Botpress Studio</li></ul>
      </td>
    </tr>

    <tr>
      <td>
        Terms and Conditions
      </td>

      <td>
        [Terms and Conditions](https://botpress.com/company/terms)
      </td>
    </tr>

  </tbody>
</table>

## Enterprise-Specific Features​

<table>
  <tr>
    <td>**Feature**</td>
    <td>**Description**</td>
  </tr>
  <tr>
    <td>Enhanced Enterprise Security for bot users</td>
    <td>Identity transmission - securely transmit the user identity to the Webchat from the host web page</td>
  </tr>
  <tr>
    <td>Role-based access control (RBAC)</td>
    <td>
      RBAC - Users can be assigned roles, and permissions can be managed with regards to these roles in terms of giving
      users read and/or write access to specific features
    </td>
  </tr>
  <tr>
    <td>Single-Sign On (SSO)</td>
    <td>
      Seamlessly link Botpress to your identity provider, OAuth2 for Google, GitHub, Azure
      <br />
      Talk to sales for more information
    </td>
  </tr>
  <tr>
    <td>Scalability</td>
    <td>Botpress has you covered: your bot solution adapts instantaneously as your user base grows</td>
  </tr>
  <tr>
    <td>Monitoring</td>
    <td>
      Directly monitor messages left on your community plan
      <br />
      Set up alerts for messages and keep an eye on your monthly message traffic
    </td>
  </tr>
  <tr>
    <td>Enterprise Support</td>
    <td>
      Advanced Botpress technical support
      <br />
      Standard: EST business hours
      <br />
      Premium: 24/7
      <br />
      SLA
    </td>
  </tr>
  <tr>
    <td>Integrations</td>
    <td>

    For a full list of integrations check out our [integration hub](https://botpress.com/hub)

    </td>

  </tr>
  <tr>
    <td>Collaboration</td>
    <td>
      Real-time collaboration, with workspaces to organize both bots and developer work
      <br />
      Realtime collaborative interface (with lock management)
      <br />
      Workspaces - logical unit that groups up your conversational assistants based on the purpose of the bots or
      for something more granular such as for a specific task, etc.
    </td>
  </tr>
</table>

---

# Languages

Source: https://botpress.com/docs/studio/guides/advanced/additional-information/languages

import YouTube from '@/components/YouTube.astro'

<Picture src={languagesImg} alt="" />

## Supported Languages

With Botpress, you can build bots that are able to converse with people in more than 100+ languages!

<table>
  <thead>
    <tr>
      <th>

      </th>

      <th>

      </th>

      <th>

      </th>

      <th>

      </th>

      <th>

      </th>
    </tr>

  </thead>

  <tbody>
    <tr>
      <td>
        Afrikaans
      </td>

      <td>
        Albanian
      </td>

      <td>
        Alemannic
      </td>

      <td>
        Amharic
      </td>

      <td>
        Arabic
      </td>
    </tr>

    <tr>
      <td>
        Aragonese
      </td>

      <td>
        Armenian
      </td>

      <td>
        Assamese
      </td>

      <td>
        Asturian
      </td>

      <td>
        Azerbaijani
      </td>
    </tr>

    <tr>
      <td>
        Bashkir
      </td>

      <td>
        Basque
      </td>

      <td>
        Bavarian
      </td>

      <td>
        Belarusian
      </td>

      <td>
        Bengali
      </td>
    </tr>

    <tr>
      <td>
        Bihari
      </td>

      <td>
        Bishnupriya Manipuri
      </td>

      <td>
        Bosnian
      </td>

      <td>
        Breton
      </td>

      <td>
        Bulgarian
      </td>
    </tr>

    <tr>
      <td>
        Burmese
      </td>

      <td>
        Catalan
      </td>

      <td>
        Cebuano
      </td>

      <td>
        Central Bicolano
      </td>

      <td>
        Chechen
      </td>
    </tr>

    <tr>
      <td>
        Chinese (Simplified and Traditional)
      </td>

      <td>
        Chuvash
      </td>

      <td>
        Corsican
      </td>

      <td>
        Croatian
      </td>

      <td>
        Czech
      </td>
    </tr>

    <tr>
      <td>
        Danish
      </td>

      <td>
        Divehi
      </td>

      <td>
        Dutch
      </td>

      <td>
        Eastern Punjabi
      </td>

      <td>
        Egyptian Arabic
      </td>
    </tr>

    <tr>
      <td>
        Emilian-Romagnol
      </td>

      <td>
        Erzya
      </td>

      <td>
        Esperanto
      </td>

      <td>
        Estonian
      </td>

      <td>
        Fiji Hindi
      </td>
    </tr>

    <tr>
      <td>
        Finnish
      </td>

      <td>
        French
      </td>

      <td>
        Galician
      </td>

      <td>
        Georgian
      </td>

      <td>
        German
      </td>
    </tr>

    <tr>
      <td>
        Goan Konkani
      </td>

      <td>
        Greek
      </td>

      <td>
        Gujarati
      </td>

      <td>
        Haitian
      </td>

      <td>
        Hebrew
      </td>
    </tr>

    <tr>
      <td>
        Hill Mari
      </td>

      <td>
        Hindi
      </td>

      <td>
        Hungarian
      </td>

      <td>
        Icelandic
      </td>

      <td>
        Ido
      </td>
    </tr>

    <tr>
      <td>
        Ilokano
      </td>

      <td>
        Indonesian
      </td>

      <td>
        Interlingua
      </td>

      <td>
        Irish
      </td>

      <td>
        Italian
      </td>
    </tr>

    <tr>
      <td>
        Japanese
      </td>

      <td>
        Javanese
      </td>

      <td>
        Kannada
      </td>

      <td>
        Kapampangan
      </td>

      <td>
        Kazakh
      </td>
    </tr>

    <tr>
      <td>
        Khmer
      </td>

      <td>
        Kirghiz
      </td>

      <td>
        Korean
      </td>

      <td>
        Kurdish (Kurmanji)
      </td>

      <td>
        Kurdish (Sorani)
      </td>
    </tr>

    <tr>
      <td>
        Latin
      </td>

      <td>
        Latvian
      </td>

      <td>
        Limburgish
      </td>

      <td>
        Lithuanian
      </td>

      <td>
        Lombard
      </td>
    </tr>

    <tr>
      <td>
        Low Saxon
      </td>

      <td>
        Luxembourgish
      </td>

      <td>
        Macedonian
      </td>

      <td>
        Maithili
      </td>

      <td>
        Malagasy
      </td>
    </tr>

    <tr>
      <td>
        Malay
      </td>

      <td>
        Malayalam
      </td>

      <td>
        Maltese
      </td>

      <td>
        Manx
      </td>

      <td>
        Marathi
      </td>
    </tr>

    <tr>
      <td>
        Mazandarani
      </td>

      <td>
        Meadow Mari
      </td>

      <td>
        Minangkabau
      </td>

      <td>
        Mingrelian
      </td>

      <td>
        Mongolian
      </td>
    </tr>

    <tr>
      <td>
        Mangolian
      </td>

      <td>
        Nahautl
      </td>

      <td>
        Neapolitan
      </td>

      <td>
        Nepali
      </td>

      <td>
        Newar
      </td>
    </tr>

    <tr>
      <td>
        North Frisian
      </td>

      <td>
        Northern Sotho
      </td>

      <td>
        Norwegian (Bokmål)
      </td>

      <td>
        Norwegian (Nynorsk)
      </td>

      <td>
        Occitan
      </td>
    </tr>

    <tr>
      <td>
        Oriya
      </td>

      <td>
        Ossetian
      </td>

      <td>
        Palatinate German
      </td>

      <td>
        Pashto
      </td>

      <td>
        Persian
      </td>
    </tr>

    <tr>
      <td>
        Piedmontese
      </td>

      <td>
        Polish
      </td>

      <td>
        Portuguese
      </td>

      <td>
        Quechua
      </td>

      <td>
        Romanian
      </td>
    </tr>

    <tr>
      <td>
        Romansh
      </td>

      <td>
        Russian
      </td>

      <td>
        Sakha
      </td>

      <td>
        Sanskrit
      </td>

      <td>
        Sardinian
      </td>
    </tr>

    <tr>
      <td>
        Scots
      </td>

      <td>
        Scottish Gaelic
      </td>

      <td>
        Serbian
      </td>

      <td>
        Serbo-Croatian
      </td>

      <td>
        Sicilian
      </td>
    </tr>

    <tr>
      <td>
        Sindhi
      </td>

      <td>
        Sinhalese
      </td>

      <td>
        Slovak
      </td>

      <td>
        Slovenian
      </td>

      <td>
        Somali
      </td>
    </tr>

    <tr>
      <td>
        Southern Azerbaijani
      </td>

      <td>
        Spanish
      </td>

      <td>
        Sundanese
      </td>

      <td>
        Swahili
      </td>

      <td>
        Swedish
      </td>
    </tr>

    <tr>
      <td>
        Tagalog
      </td>

      <td>
        Tajik
      </td>

      <td>
        Tamil
      </td>

      <td>
        Tatar
      </td>

      <td>
        Telugu
      </td>
    </tr>

    <tr>
      <td>
        Thai
      </td>

      <td>
        Tibetan
      </td>

      <td>
        Turkish
      </td>

      <td>
        Turkmen
      </td>

      <td>
        Ukrainian
      </td>
    </tr>

    <tr>
      <td>
        Upper Sorbian
      </td>

      <td>
        Urdu
      </td>

      <td>
        Uyghur
      </td>

      <td>
        Uzbek
      </td>

      <td>
        Venetian
      </td>
    </tr>

    <tr>
      <td>
        Vietnamese
      </td>

      <td>
        Volapük
      </td>

      <td>
        Walloon
      </td>

      <td>
        Waray
      </td>

      <td>
        Welsh
      </td>
    </tr>

    <tr>
      <td>
        West Flemish
      </td>

      <td>
        West Frisian
      </td>

      <td>
        Western Punjabi
      </td>

      <td>
        Yiddish
      </td>

      <td>
        Yoruba
      </td>
    </tr>

    <tr>
      <td>
        Zazaki
      </td>

      <td>
        Zeelandic
      </td>

      <td>

      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

  </tbody>
</table>

<br />

## Translator Agent

<YouTube url="https://www.youtube.com/embed/SIrmuihqNhs?si=FXZQJ59rRLW07D2D" />

<Picture src={translatorAgentImg} alt="" />

The Translator Agent allows your bot to interact with users in different languages, breaking language barriers and expanding the range of your bot's audience.

### Configuration

- **Automatically Detect User Language** - When enabled, the Translator Agent will automatically detect the user's language from their input.

Activating this feature consequently sets the `{{user.TranslatorAgent.language}}` variable when it's not already defined.

### Exposed Variables

- **user.TranslatorAgent.language**: This variable represents the detected language of the user.

### Example - setting language to french

1. Open the Toolbox Cards and drag the **Set User Language** Card into your first node(ideally).
2. Specify a language. In this case, we will use `fr` for French.

The Translator Agent automatically translates the bot's responses into the user's language once activated. If you wish to define the user's language manually, you can directly set the `{{user.TranslatorAgent.language}}` variable.

This variable is set to `null` by default, which means that the Translator Agent will automatically detect the user's language from their input.

### Resetting the language

Drag the **Reset User Language** Card into your Workflow. This will reset the `{{user.TranslatorAgent.language}}` variable to `null`.

You can do this in Execute Code card as well:

```javascript
//use null to reset the language; otherwise, set it to a language code
{{user.TranslatorAgent.language}} = null;
```

---

# Platform Limits

Source: https://botpress.com/docs/studio/guides/advanced/additional-information/limits-and-quotas-of-botpress-cloud

## Limits and Quotas of Botpress Cloud

Botpress sets certain limits and quotas to ensure the stability of the platform and the bots created by customers and the community.

### Limits

| **Limit**                                                                                                                           | **Amount**                  | **Technical Name**                |
| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------- |
| The maximum size for the bot settings                                                                                               | 20KB                        | Bot Configuration                 |
| The maximum number of integrations that can be installed in a bot                                                                   | 30                          | Bot Installed Integrations        |
| The maximum size for integration settings                                                                                           | 20KB                        | Bot Integration Configuration     |
| The maximum number of [Schedule Triggers](/studio/concepts/cards/fixed-schedule.md) per bot                                            | 40                          | Bot Recurring Events              |
| The maximum size for the Schedule Trigger event payload                                                                             | 128KB                       | Bot Recurring Event Payload Size  |
| The maximum number of events (used as Triggers) that an integration can define in its definition file                               | 20                          | Event Definition                  |
| The maximum number of channels an integration can support (e.g., direct messages, public channels, threads)                         | 10                          | Integration Channels              |
| The maximum number of message types that an integration channel can support                                                         | 20                          | Integration Channel Message Types |
| The maximum number of unique OAuth identifiers an integration can have                                                              | 50                          | Integration OAuth Identifier      |
| The maximum number of versions a custom integration can have                                                                        | 50                          | Integration Versions              |
| The maximum size for the payload of messages                                                                                        | 128KB                       | Message Payload Size              |
| The maximum size for the integration                                                                                                | 20KB                        | Schema Size schemas               |
| The maximum number of free-form object variables a bot or an integration can have (limited by the Conversation State Size of 128KB) | 5                           | State Definitions                 |
| The maximum size for the conversation state serialized as JSON                                                                      | 128KB                       | Conversation State Size           |
| The maximum number of tag definitions per bot                                                                                       | 50                          | Tag Definitions                   |
| The maximum number of columns per table                                                                                             | 20                          | Table columns                     |
| End-user message / event max throughput                                                                                             | 600 requests / minute / bot | API limit                         |
| Maximum size of deployed bot (excluding file storage)                                                                               | 100MB                       | Bot Size                          |

### Quotas

Quotas are limits that can be increased depending on the plan you're subscribed to. For more information, please check our [detailed pricing page](https://botpress.com/pricing).

| **Quota**                                                                                                                                                                                         | **Amount**                  | **Technical Name**     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------- |
| The maximum time for a bot to process a message or an event before timing out (not the same as [Inactivity Timeout](/studio/concepts/bot-settings.md#inactivity-timeout))                            | 60s                         | Invocation Timeout     |
| The maximum combined size of documents uploaded to be sent as media messages (e.g., Images, Audios, Videos, Files, and Cards)                                                                     | 100MB                       | Storage Size           |
| The maximum number of bots per workspace                                                                                                                                                          | 5                           | Amount of Bots         |
| The maximum number of members that can be added to a workspace (Collaborators can have roles such as Viewer, Billing Manager, Developer, Manager, Administrator)                                  | 3                           | Amount of Members      |
| The maximum number of vectors (content chunks) in a Knowledge Base per bot (roughly equivalent to 100MB of documents)                                                                             | 5,000                       | Knowledge Base Vectors |
| The maximum number of records/items that can be stored in a table per bot                                                                                                                         | 5,000                       | Table Rows             |
| The maximum number of times a bot can be invoked per month (An invocation occurs when a new conversation is created, when a conversation resumes after a timeout, and when a Trigger is executed) | 25,000                      | Invocation Calls       |
| The maximum number of times a bot can call cognitive (AI) services per month                                                                                                                      | 4,000                       | Cognitive Calls        |
| The maximum number of bot invocations per minute                                                                                                                                                  | 100                         | Bot Rate Limit         |
| The maximum number of custom integrations that can be created per workspace                                                                                                                       | 20                          | Owned Integrations     |
| The maximum number of AI model credits that can be used per month                                                                                                                                 | 5,000                       | LLM Model Credits      |
| The maximum number of row sizes in a table. However, you can increase it from the factors section from the API ([Read More Here](/studio/concepts/tables.md#create-table))                           | 4kb                         | Table Row Size         |
| The maximum number of HTTP requests sent from the emulator                                                                                                                                        | 30 requests / minute / bot  | External calls         |
| Botpress API limit [https://api.botpress.cloud/](https://api.botpress.cloud/)\*                                                                                                                   | 100 requests / second       | API limit              |
| Integrations API limit [https://webhook.botpress.cloud/](https://webhook.botpress.cloud/)\*                                                                                                       | 100 requests / second / bot | API limit              |

---

# Tips & Tricks

Source: https://botpress.com/docs/studio/guides/advanced/additional-information/tips-tricks

import { Note, Info } from '@/components/callouts'

<Picture src={gettingStartedTipsTricksImg} alt="" />

## Using Markdown in Botpress

Markdown is a lightweight markup language that you can use to add formatting elements to plain text documents. It's a simple way to add formatting to your text. You can use Markdown in Botpress to format your text in the following ways:

| Markdown Syntax | Example                                                                        |
| --------------- | ------------------------------------------------------------------------------ |
| Bold            | `**Bold**`                                                                     |
| Italic          | `*Italic*`                                                                     |
| Strikethrough   | `~~Strikethrough~~`                                                            |
| Code            | `Code`                                                                         |
| Code Block      | `Code Block`                                                                   |
| Link            | `[botpress.com](https://www.botpress.com)`                                     |
| Image           | `![botpress logo](https://avatars.githubusercontent.com/u/23510677?s=200&v=4)` |
| Unordered List  | `- Item 1`                                                                     |
| Ordered List    | `1. Item 1`                                                                    |
| Horizontal line | `---`                                                                          |

<Info>
Info

Markdown is supported only in Webchat Integration

</Info>

## Timely Greeting

Pick an Execute Code card and enter the prompt as "Timely Greeting". It will generate the following code:

```javascript
const currentTime = luxon.DateTime.now()
const currentHour = currentTime.hour

let timelyGreeting = ''
if (currentHour >= 0 && currentHour < 12) {
  timelyGreeting = 'Good morning'
} else if (currentHour >= 12 && currentHour < 18) {
  timelyGreeting = 'Good afternoon'
} else {
  timelyGreeting = 'Good evening'
}

workflow.timelyGreeting = timelyGreeting
```

This code will set the variable `timelyGreeting` to the appropriate greeting based on the current time. Make sure to create this variable in your Workflow.

## Using External APIs in Botpress

These are guides on using the Execute Code Card in Botpress to access external APIs to read and update data.

The API calls will be performed using the Botpress built-in Axios client, and the code will run in the Execute Code Card.

### Example - [The Bored API](https://www.boredapi.com/)

The Bored API's motto is : Let's find you something to do! We will be using Bored API as an example of how to call APIs to fetch information.

1. (Optional) Create a Workflow variable to store the information retrieved from the API. In this example, we will create a variable named `participantType`.
2. Pick the **Execute Code** Card and disable the Generative AI by clicking on the ✨ button.
3. Paste the following code in the Execute Code Card:

```typescript
const response = await axios.get('https://www.boredapi.com/api/activity?participants=1')
workflow.participantType = response.data.activity
```

Response:

```typescript
    {
      "activity": "Go stargazing",
      "type": "relaxation",
      "participants": 1,
      "price": 0,
      "link": "",
      "key": "8832605",
      "accessibility": 0.1
    }
```

### Send Emails using [SendGrid API](https://sendgrid.com/)

You can choose any other provider, like Gmail, Microsoft, etc. But you will need to change the code based on the provider you want to integrate with.

1. **Create a free SendGrid[account](https://sendgrid.com/pricing/ 'account')**: For trial purposes.
2. **Navigate to Email API**: After logging into your new account, click on **Email API** in the menu, then select **Integration Guide**.
3. **Create an Identity**: Provide your details when prompted and click **Create**. Verify your identity through the verification email you receive.
4. **Create an[API Key](https://app.sendgrid.com/settings/api_keys 'API Key')**: Click on **Create API Key** at the top right corner and name the key for your reference.
5. **Save the API Key**: After creating the key, copy the key value for later use. Remember to keep it safe.
6. **Configure Botpress**: Open your bot in Botpress, and add an **Execute Code** card. Ensure to disable the generative AI within the card.
7. **Paste the Code**: Adjust the following variables in the code and paste it into the card:
   - `sendgrid_api_key`: This is the API key generated in the SendGrid [API Key](https://app.sendgrid.com/settings/api_keys 'API Key').
   - `from_email`: This is the email you configured as the sender.
   - `to_email`: This is the email to which you are sending.

```typescript
const sendgrid_api_key = *********
const from_email = '**************'
const to_email = '*****************'

const response = await axios.post(
  'https://api.sendgrid.com/v3/mail/send',
  {
    personalizations: [{to: [{email: to_email}]}],
    from: {
      email: from_email
    },
    subject: 'Sending with SendGrid is Fun',
    content: [
      {
        type: 'text/plain',
        value: 'and easy to do anywhere, even with cURL'
      }
    ]
  },
  {
    headers: {
      Authorization: 'Bearer ' + SENDGRID_API_KEY,
      'Content-Type': 'application/json'
    }
  }
)
```

After successfully integrating the SendGrid API into Botpress, it's time to test it.\
For more information: [https://docs.sendgrid.com/for-developers/sending-email/api-getting-started](https://docs.sendgrid.com/for-developers/sending-email/api-getting-started)

### Use ChatGPT API in Execute Code

If you are using Botpress and want to integrate the ChatGPT API to generate AI-powered responses for your bot, follow these simple steps:

Step 1: Create a variable in your Botpress Workflow to store the ChatGPT API's response.

Step 2: Add the **Execute Code** card to your Botpress Workflow and paste the code below:

```typescript
const apiKey = '<OpenAI's APIKey>';
const {data} = await axios.post("https://api.openai.com/v1/chat/completions", {
  "model": "gpt-3.5-turbo-0301",
  "messages": [{"role": "user", "content": event.preview}]
}, { headers: {'Authorization': `Bearer ${apiKey}`}});

workflow.variableName = data.choices[0].message.content;
```

Make sure to replace **`<OpenAI's APIKey>`** with your actual OpenAI API key, and `variableName` with the name of the variable you created in Step 1.

Step 3: Test your bot in the Botpress Emulator to see if it's generating AI-powered responses.

<Note>
Note

It's important to note that using this method, ChatGPT doesn't preserve the context of the messages that you've sent. However, it's a great way to get started with integrating AI-powered responses into your bot without needing any technical knowledge.

</Note>

---

# Execute Code

Source: https://botpress.com/docs/studio/guides/advanced/execute-code

The Execute Code card allows you to run custom code (in JavaScript) in the context of the current Workflow. This code can also be generated automatically using AI. This is useful for making API calls, performing calculations, or any other custom logic you may need.

> 👍 Generative AI
>
> Using this natural language feature you can instruct AI to generate the different pieces of code your bot needs to run, and it's contextual, considers your variables and your conversation's context.

<br />

## Inbuilt Packages

The below packages are already imported and available for use in the Execute Code card.

- [Axios](https://axios-http.com/docs/api_intro)
- [Lodash](https://lodash.com/docs/4.17.15)
- [Moment Luxon](https://moment.github.io/luxon/#/?id=luxon)

<br />

## How to Use

1. Drag and drop the Execute Code card into a Node or click on the **+ Add Card** button in the Node and select Execute Code.
2. Write what you want to do in the input field.

For example, if you want to make an API call, you can write the following:

```
  Make an API Call to weatherAPI and store the result in a Workflow variable
```

3. Check if the Code satisfies your needs and **Accept** or **Undo** the changes.
4. This will automatically generate the description of the code in the Code Card.

<br />

## Versioning

Versioning allows you to go back and forth between different versions of the code. This is useful if you want to try out different versions of the code and see which one works best.

1. Once you **Accept**, you can rewrite the code and **Accept** again. This will create a new version of the code.
2. You can check the changes between versions, and once you're satisfied with the code, you can **Accept** it or **Undo** it.
3. Use the arrows to go back and forth between versions.

<br />

## Examples

Input: **I want to find the difference between the variables `startDate` and the `endDate`**

Generated Output:

```typescript
const startDate = luxon.fromISO(workflow.startDate) // convert the startDate string to a luxon DateTime object
const endDate = luxon.fromISO(workflow.endDate) // convert the endDate string to a luxon DateTime object
const diffInDays = endDate.diff(startDate, 'days').toObject().days // find the difference between the two dates in days
// store the difference in days in the Workflow variable 'dateDiff' as requested
workflow.dateDiff = diffInDays
```

---

Input: **I want to get all my issues from Jira filtered by what isn't done**

Generated Output:

```typescript
const jiraUrl = 'https://your-jira-url.com'
const jiraUsername = 'your-jira-username'
const jiraPassword = 'your-jira-password'

// get the current date and time in ISO format
const now = luxon.local().toISO()

// create the JQL query to get all issues that aren't done
const jql = `status != Done AND updated >= "${now}" ORDER BY updated DESC`

// set the request headers for Jira API
const headers = {
  'Content-Type': 'application/json',
  Authorization: `Basic ${btoa(`${jiraUsername}:${jiraPassword}`)}`,
}

// make the request to Jira API to get all issues that aren't done
const response = await axios.get(`${jiraUrl}/rest/api/2/search?jql=${jql}`, {
  headers,
})

// filter the response to only keep the issues that aren't done
const issues = _.filter(response.data.issues, (issue) => issue.fields.status.name !== 'Done')
```

<br />

## Transitioning from Another Language to Botpress

If you're transitioning from another programming language to Botpress, we've got you covered. With the power of ChatGPT, converting simple code snippets, such as making API requests, is now easier than ever.

Step 1: Take your existing code from another programming language. This could be in a language like Python, C#, or any other language you're coming from.

Step 2: Paste the code snippet you have into ChatGPT and add this instruction below it.

```text
Convert the code above to deno. Save the variable results to the Workflow object (global object available in the code block). Use axios for http requests and use it directly without the "async" keyword. For date management use the luxon library. For string manipulation use the lodash library. All of these libraries are already imported.
```

Step 3: Paste the result of ChatGPT into the Execute Code card.

Step 4: Test your code and make sure it works as expected.

Step 5: If you need to make any changes, you can do so by editing the code directly or by adding new instructions in the top input of the Execute Code card.

---

# Transition

Source: https://botpress.com/docs/studio/guides/advanced/transition

A Transition is like a "decision point" in a conversation with a bot, where the bot has to decide what to do next based on what the user has said or done. It's like a set of instructions that the bot follows to determine which "path" to take in the conversation.

The transition statement is what tells the bot which response or question to provide based on what the user has said or done.

## Expression

An Expression transition is a conditional statement that tells the bot which node should be processed next if the condition is met. It uses generative AI to generate the conditions using plain text.

This type of transition allows you to check user input, user variables, Workflow variables, and even create advanced JavaScript expressions to determine which node the bot should transition to next.

You can use a combination of these checks to create complex conditions that will determine which node the bot will transition to next.

<Note>
**Generative AI Transitions**

You can use generative AI to generate your conditions using plain text. In order to achieve what you exactly want, here are some examples that should guide you, but you aren't limited to it:

</Note>

### Always transition to another node

There are two ways to make sure that a transition always triggers:

The recommended approach is to click and drag starting from the circle on the bottom-right of nodes, next to the "Add Card" button. Transitions created this way always trigger when the user reaches the end of the node.

You can also add an Expression card by creating an `Expression Transition` with the label "Always" and by pressing `Enter`. The code generator will insert `true` in the expression input. Anything below this `Transition` in the `Node` will never run.

## Intent

An Intent transition allows you to create an inline intent (or node-specific intent). Only if this intent is elected will the condition be met.

This type of transition is useful when you want to create a specific response for a particular intent. You can create an\
intent for a specific node, and the bot will transition to that node only if that intent is detected in the user's message.

For example, if a user says "I want to book a hotel room," the bot can transition to a node that's specific to handling\
hotel room bookings.

---

# Adding user authentication to your bot via OAuth

Source: https://botpress.com/docs/studio/guides/how-to/how-to-setup-oauth-with-github-in-botpress-using-integrations

import YouTube from '@/components/YouTube.astro'

OAuth can be very useful especially in cases where validating the identify of the user is crucial. In the example that follows we walk through how we was able to setup OAuth verification with GitHub as my platform of choice in our Botpress bot.

This was accomplished with the help of a custom integration for setting up OAuth with GitHub.

## Demo

**When the user is authenticated**

<YouTube url="https://www.youtube.com/embed/c0J5woV0UMQ?si=VBLHrUigHiUYzm0m" />

**When the user is unauthenticated**

<YouTube url="https://www.youtube.com/embed/c0J5woV0UMQ?si=2bh-MFniNSxgw_rL" />

## Bot Setup

The bot setup is straightforward. First, the user is prompted to log in by clicking on a link generated by the integration. Once the login is successful, an event is emitted. This event is captured by a trigger node, which then hands off control to an autonomous node.

<Picture src={oauthBotAuthImg} alt="" />

## Integration

The integration has a couple of responsibilities:

1. Generating the OAuth link that users will click on.
2. Capturing a successful authentication which then emits an event containing the conversation ID and data about the authenticated user.

This is achieved using an action ( here called “Generate OAuth2 URL” ) and the integration’s Botpress webhook handler. The webhook captures successful authentication and emits a Botpress event ( in this case, “User Authenticated” ).

### Writing this integration

You can use the [Building](doc:building-integrations) to bootstrap an integration, then add the following code as a starting point to achieve the above result. Once you get it working, we suggest you modify the integration to fit your purposes.

In `integration.definition.ts` we define the events (which bot builders can hook onto in the Studio), and actions which allow for generating the URL that should be displayed to the end user.

```typescript integration.definition.ts
import { conversation, IntegrationDefinition, z } from '@botpress/sdk'
import { integrationName } from './package.json'
import { DEFAULT_STORE_KEY } from 'src/store'

export default new IntegrationDefinition({
  name: integrationName,
  version: '0.0.1',
  readme: 'hub.md',
  icon: 'icon.svg',
  configuration: {
    schema: z.object({
      clientId: z.string(),
      clientSecret: z.string(),
      state: z.string().default('secure_random_string').hidden(), // This is used for the authentication handshake, you can change it to a random string.
    }),
  },
  events: {
    onUserAuthenticated: {
      title: 'User Authenticated',
      description: 'Fires when a user has been authenticated',
      schema: z.object({
        userData: z.any(),
        conversationIdxx: z.string(),
      }),
    },
  },
  actions: {
    generateUrl: {
      title: 'Generate OAuth2 URL',
      description: 'Generates an OAuth2 URL to authenticate the user',
      input: {
        schema: z.object({
          conversationId: z.string().default('{{event.conversationId}}').hidden(),
        }),
      },
      output: {
        schema: z.object({
          url: z.string(),
        }),
      },
    },
  },
  states: {
    [DEFAULT_STORE_KEY]: {
      type: 'integration',
      schema: z.object({
        bpWebhookUrl: z.string(),
        conversationId: z.string(),
      }),
    },
  },
})
```

In src/index.ts is the main logic for generating a shareable sign-up URL for OAuth, and a handler method to handle the OAuth response.

```typescript index.ts
import * as sdk from '@botpress/sdk'
import * as bp from '.botpress'
import { Store } from './store'

export default new bp.Integration({
  register: async ({ webhookUrl, client, ctx }) => {
    const store = new Store(client, ctx)
    await store.initialize({
      bpWebhookUrl: webhookUrl,
      conversationId: '',
    })
    console.log('Integration registered')
  },
  unregister: async () => {},
  actions: {
    generateUrl: async ({ client, input, ctx }) => {
      const store = new Store(client, ctx)
      await store.load()

      await store.set('conversationId', input.conversationId)
      const webhookUrl = await store.get('bpWebhookUrl')

      const clientId = ctx.configuration.clientId
      const redirectUri = webhookUrl // Redirect back to the integration
      const state = ctx.configuration.state // For CSRF protection
      const scope = 'read:user' // Request access to read user profile

      const githubOAuthUrl = `https://github.com/login/oauth/authorize?client_id=${clientId}&redirect_uri=${encodeURIComponent(
        redirectUri
      )}&scope=${scope}&state=${state}`

      return { url: githubOAuthUrl }
    },
  },
  channels: {},
  handler: async ({ req, client, ctx }) => {
    const store = new Store(client, ctx)
    await store.load()
    const webhookUrl = await store.get('bpWebhookUrl')

    // Construct a URLSearchParams object
    const params = new URLSearchParams(req.query)

    // Extract query parameters
    const code = params.get('code') // Extract 'code'
    const sec_string = params.get('state') // Extract 'state'

    // Verify the `state` to protect against CSRF
    if (sec_string !== ctx.configuration.state) {
      return { status: 403, message: 'Invalid state' }
    }

    // Exchange the code for an access token
    const tokenResponse: any = await fetch('https://github.com/login/oauth/access_token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
      body: JSON.stringify({
        client_id: ctx.configuration.clientId,
        client_secret: ctx.configuration.clientSecret,
        code,
        redirect_uri: webhookUrl,
      }),
    }).then((res) => res.json())

    // Fetch user data
    const userData: any = await fetch('https://api.github.com/user', {
      headers: {
        Authorization: `Bearer ${tokenResponse.access_token}`,
      },
    }).then((res) => res.json())

    // Send a message to the user
    const conversationId = await store.get('conversationId')

    await client.createEvent({
      type: 'onUserAuthenticated',
      conversationId: conversationId,
      payload: {
        conversationIdxx: conversationId,
        userData: userData,
      },
    })

    return { status: 200, message: 'Success' }
  },
})
```

In src/store.ts we add some logic to be able to save authentication parameters which will help us know who is who when getting a callback request from OAuth.

```typescript store.ts
import * as sdk from '@botpress/sdk'

export const DEFAULT_STORE_KEY = 'globalStore'

export class Store {
  private client: sdk.IntegrationSpecificClient<any>
  private ctx: sdk.IntegrationContext
  private globalStoreKey: string
  private validKeys: string[] = []

  constructor(
    client: sdk.IntegrationSpecificClient<any>,
    ctx: sdk.IntegrationContext,
    globalStoreKey = DEFAULT_STORE_KEY
  ) {
    this.client = client
    this.ctx = ctx
    this.globalStoreKey = globalStoreKey
  }

  private async fetchGlobalStore(): Promise<Record<string, any>> {
    const result = await this.client.getState({
      type: 'integration',
      id: this.ctx.integrationId,
      name: this.globalStoreKey,
    })
    return result.state.payload || {} // Default to an empty object if no state exists
  }

  private async updateGlobalStore(store: Record<string, any>): Promise<void> {
    console.log('updating store', store)
    await this.client.setState({
      type: 'integration',
      id: this.ctx.integrationId,
      name: this.globalStoreKey,
      payload: store,
    })
  }

  async initialize(initialState: Record<string, any>): Promise<void> {
    this.validKeys = Object.keys(initialState)
    await this.updateGlobalStore(initialState)
  }

  async load(): Promise<void> {
    const store = await this.fetchGlobalStore()
    this.validKeys = Object.keys(store)
  }

  private validateKey(key: string): void {
    if (!this.validKeys.includes(key)) {
      throw new Error(`Key ${key} isn't a valid key, valid keys are: ${this.validKeys.join(', ')}`)
    }
  }

  async set(key: string, value: any): Promise<void> {
    this.validateKey(key)
    const store = await this.fetchGlobalStore()
    console.log('got store', store)
    store[key] = value // Update the key in the global store
    await this.updateGlobalStore(store) // Save the updated store back
  }

  async get(key: string): Promise<any> {
    this.validateKey(key)
    const store = await this.fetchGlobalStore()
    return store[key] // Retrieve the value for the key
  }
}
```

<br />

After adding this code, deploy it to the bot you want to work on, and configure it using GitHub parameters (or whatever platform you'd like to port this to) and hit "Save Configuration".

If you'd like to try out the GitHub example above, you can use this link to create the credentials :

[https://github.com/settings/developers#oauth-apps](https://github.com/settings/developers#oauth-apps)

{/* vale Botpress.workflows = NO */}
The "Authorization callback URL" should be your webhook URL, located in the configuration page of the integration. There is no need to enable the device flow.
{/* vale Botpress.workflows = YES */}

That's it, now you can publish your bot, and try it out. Once that works, feel free to use this code as a starting point for your OAuth Integration.

---

# Embed Webchat

Source: https://botpress.com/docs/webchat/get-started/embedding-webchat

Manually add Webchat to your website.

You can manually embed the Webchat window in an HTML `<div>`. This is useful if you want to include the Webchat window in a specific section of your website.

<Note>
  If you just want to quickly add a bot to your website, use the [Quickstart guide](/webchat/get-started/quick-start.md).
</Note>

<Info>
You will need:

- A [published bot](/studio/get-started/quick-start.md)
- Basic familiarity with HTML

</Info>

<Steps titleSize="h2">

  <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>
      <Picture alt="Embed code from Dashboard" class="block dark:hidden" src={embedCodeDashboardImg} />
      <Picture alt="Embed code from Dashboard" class="hidden dark:block" src={embedCodeDashboardDarkImg} />
    </Frame>

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

      ```js title="https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js" [expandable]
      window.botpress.init({
          "botId": "xxxxxxxxxxxxxxxxxxxxxx",
          "configuration": {
              "website": {},
              "email": {},
              "phone": {},
              "termsOfService": {},
              "privacyPolicy": {},
              "variant": "soft",
              "themeMode": "light",
              "fontFamily": "inter"
          },
          "clientId": "xxxxxxxxxxxxxxxxxxxxxx"
      });
      ```

  </Step>

  <Step title="Add Webchat to an HTML div">
    Now you can embed Webchat directly in an HTML `<div>` on your website:

    ```html {8} [expandable]
    <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>
    ```

    <Tip>
        By default, the code above will make Webchat take up your entire screen. To change the size and position of the Webchat window, update the `bpWebchat` class.
      </Tip>

  </Step>
  
</Steps>