> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Botpress

The Botpress connector lets your AI agent act in each user's Botpress account. Each user connects their own Botpress access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 58 tools.

**Authentication:** Bearer Token
**Categories:** AI, Communication
**Tools:** 58: 31 read, 19 write, 8 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=BOTPRESS)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Botpress connection

   In **AgentKit > Connections**, create a Botpress connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'botpress'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Botpress:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'botpress_account_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "botpress"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Botpress:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="botpress_account_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Botpress credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'botpress_account_get',
  toolInput: {},
  connector: 'botpress',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="botpress_account_get",
    tool_input={},
    connection_name="botpress",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `botpress_account_get`

Get Account · Read-only

Get the Botpress account that owns the personal access token.
Returns account.
Use this to confirm the connection.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `botpress_bot_analytics_get`

Get Bot Analytics · Read-only

Get a bot's usage analytics (users, sessions, messages, LLM calls) for a date range.
Returns records.
Get the bot ID from botpress_bots_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end_date` (`string`, required): End date/time (inclusive) Example: 2026-01-31T23:59:59Z
- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `start_date` (`string`, required): Start date/time (inclusive) Example: 2026-01-01T00:00:00Z
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890

Example input: `{"end_date":"<end_date>","id":"<id>","start_date":"<start_date>","workspace_id":"<workspace_id>"}`

### `botpress_bot_get`

Get Bot · Read-only

Get one bot's definition, integrations, status and settings.
Returns bot.
Get the bot ID from botpress_bots_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890

Example input: `{"id":"<id>","workspace_id":"<workspace_id>"}`

### `botpress_bot_issue_get`

Get Bot Issue · Read-only

Get one bot issue with its category, count and last occurrence.
Returns issue.
Get the issue ID from botpress_bot_issues_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `issue_id` (`string`, required): Issue ID. Example: iss_01HZX5K9ABCDEF
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890

Example input: `{"id":"<id>","issue_id":"<issue_id>","workspace_id":"<workspace_id>"}`

### `botpress_bot_issues_list`

List Bot Issues · Read-only

List the runtime issues (errors) recorded for a bot.
Returns issues, meta.
Use botpress_bot_issue_get for one issue. Get the bot ID from botpress_bots_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{"id":"<id>","workspace_id":"<workspace_id>"}`

### `botpress_bot_logs_get`

Get Bot Logs · Read-only

Get a bot's logs for a time range, filterable by level, user, workflow, conversation or text.
Returns logs, nextToken.
Use this to debug a bot. Get the bot ID from botpress_bots_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `time_start` (`string`, required): Beginning of the time range to get logs from. Example: 2026-01-15T00:00:00Z
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
- `conversation_id` (`string`, optional): Filter by conversation ID. Example: conv_01HZX5K9ABCDEF1234567890
- `level` (`string`, optional): Filter by log level. Example: error
- `message_contains` (`string`, optional): Filter logs where the message contains this substring. Example: timeout
- `next_token` (`string`, optional): Token to get the next page of logs. Example: eyJsYXN0SWQiOiJhYmMifQ
- `time_end` (`string`, optional): End of the time range to get logs from. Example: 2026-01-15T23:59:59Z
- `user_id` (`string`, optional): Filter by user ID. Example: user_01HZX5K9ABCDEF1234567890
- `workflow_id` (`string`, optional): Filter by workflow ID. Example: wf_01HZX5K9ABCDEFGHJKMNPQRSTV

Example input: `{"id":"<id>","time_start":"<time_start>","workspace_id":"<workspace_id>"}`

### `botpress_bots_list`

List Bots · Read-only

List the bots in a workspace, production or dev, optionally by installed integrations.
Returns bots, meta.
Use this to get bot IDs for the conversation, table and file tools.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
- `dev` (`boolean`, optional): If true, only dev bots are returned. Otherwise, only production bots are returned. Example: true
- `integration_names` (`array`, optional): Filter bots that have ALL of these integrations installed (by definition name) Example: ["value"]
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20
- `plugin_names` (`array`, optional): Filter bots that have ALL of these plugins installed (by definition name) Example: ["value"]
- `sort_direction` (`string`, optional): Sort results in this direction. One of: asc, desc. Example: asc. One of: `asc`, `desc`.
- `sort_field` (`string`, optional): Sort results by this field. One of: createdAt, updatedAt. Example: createdAt. One of: `createdAt`, `updatedAt`.

Example input: `{"workspace_id":"<workspace_id>"}`

### `botpress_conversation_get`

Get Conversation · Read-only

Get one conversation with its channel, integration and tags.
Returns conversation.
Get the conversation ID from botpress_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_conversations_list`

List Conversations · Read-only

List a bot's conversations, newest first, optionally by participant, integration, channel, date or message count.
Returns conversations, meta.
Use botpress_messages_list to read a conversation.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `after_date` (`string`, optional): Date in ISO 8601 string with UTC timezone after which the conversation was created (inclusive) Example: 2026-01-01T00:00:00Z
- `before_date` (`string`, optional): Date in ISO 8601 string with UTC timezone before which the conversation was created (inclusive) Example: 2026-01-31T23:59:59Z
- `channel` (`string`, optional): Filter by integration channel name. Example: channel
- `integration_name` (`string`, optional): Filter by integration name. Example: telegram
- `max_message_count` (`integer`, optional): Filter conversations with a message count less than or equal to this value (inclusive) Example: 10
- `min_message_count` (`integer`, optional): Filter conversations with a message count greater than or equal to this value (inclusive) Example: 10
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20
- `participant_ids` (`array`, optional): Filter by participant ids. Example: ["user_01HZX5K9ABCDEF1234567890"]
- `sort_direction` (`string`, optional): Sort results in this direction. One of: asc, desc. Example: asc. One of: `asc`, `desc`.
- `sort_field` (`string`, optional): Sort results by this field. One of: createdAt, updatedAt. Example: createdAt. One of: `createdAt`, `updatedAt`.

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_event_get`

Get Event · Read-only

Get one event with its type, payload and status.
Returns event.
Get the ID from botpress_events_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Event id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_events_list`

List Events · Read-only

List events recorded for a bot, optionally by type, conversation, user, workflow or message.
Returns events, meta.
Use botpress_event_get for one event.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `conversation_id` (`string`, optional): Filter by conversation id. Example: conv_01HZX5K9ABCDEF1234567890
- `message_id` (`string`, optional): Filter by message id. Example: msg_01HZX5K9ABCDEF1234567890
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20
- `status` (`string`, optional): Filter by status. Allowed values: pending, ignored, processed, failed, scheduled, canceled, delegated. Example: pending. One of: `pending`, `ignored`, `processed`, `failed`, `scheduled`, `canceled`, `delegated`.
- `type` (`string`, optional): Filter by event type. Example: text
- `user_id` (`string`, optional): Filter by user id. Example: user_01HZX5K9ABCDEF1234567890
- `workflow_id` (`string`, optional): Filter by workflow id. Example: wf_01HZX5K9ABCDEFGHJKMNPQRSTV

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_file_get`

Get File · Read-only

Get one file's metadata, size, status and download URL.
Returns file.
Get the ID from botpress_files_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): File ID or Key. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_file_tags_list`

List File Tags · Read-only

List the tag keys used on a bot's files.
Returns tags, meta.
Use this before filtering files by tag.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_files_list`

List Files · Read-only

List a bot's files (knowledge base documents and assets), optionally by IDs or indexing state.
Returns files, meta.
Use botpress_files_search to search inside indexed files.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `ids` (`array`, optional): Filter files by IDs. Example: ["file_01HZX5K9ABCDEF"]
- `indexed` (`boolean`, optional): Filter files by indexing state. Example: true
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20
- `sort_direction` (`string`, optional): Sort results in this direction. One of: asc, desc. Example: asc. One of: `asc`, `desc`.
- `sort_field` (`string`, optional): Sort results by this field. One of: key, size, createdAt, updatedAt, status. Example: key. One of: `key`, `size`, `createdAt`, `updatedAt`, `status`.

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_files_search`

Search Files · Read-only

Search the bot's indexed files in natural language and return the matching text passages.
Returns passages.
Use this for retrieval over the knowledge base.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `query` (`string`, required): Query expressed in natural language to retrieve matching text passages within all indexed files in the bot using semantical search. Example: refund policy
- `consolidate` (`boolean`, optional): Consolidate the results by merging matching passages from the same file into a single passage per file. The consolidated passage will include the matching passages ordered by their original position in the file (rather than by relevance score) and include hierarchical context such as the title/subtitle to which they belong. Example: true
- `context_depth` (`integer`, optional): The number of neighbor passages to prepend and append as surrounding context to the content of each returned passage (default: 1, minimum: 0, maximum: 10). Example: 10
- `include_breadcrumb` (`boolean`, optional): Prepend a breadcrumb to each passage, containing the title and subtitle(s) the passage belongs to in the file. This option is ignored when the consolidate option is set to true. Example: true
- `limit` (`integer`, optional): The maximum number of passages to return. Example: 20
- `with_context` (`boolean`, optional): Include the surrounding context with each passage in the context property of each passage. Not supported when consolidate is set to true. Example: true

Example input: `{"bot_id":"<bot_id>","query":"<query>"}`

### `botpress_hub_integration_get`

Get Hub Integration · Read-only

Get one public Hub integration with its actions, events and channels.
Returns integration.
Get the ID from botpress_hub_integrations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Integration Version ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"id":"<id>"}`

### `botpress_hub_integrations_list`

List Hub Integrations · Read-only

List or search the public integrations in the Botpress Hub.
Returns integrations, meta.
Use this to find integration names and versions.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `direction` (`string`, optional): Sort direction (asc or desc) One of: asc, desc. Example: asc. One of: `asc`, `desc`.
- `installed_by_bot_id` (`string`, optional): Bot ID. Required when filtering for installed integrations. Example: 12345
- `interface_id` (`string`, optional): Filter integrations by implemented interface ID. Example: 12345
- `interface_name` (`string`, optional): Filter integrations by implemented interface name (strict match) Example: Example name
- `limit` (`number`, optional): Maximum number of results to return per page. Example: 20
- `name` (`string`, optional): Integration Name. Example: LeadsTable
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20
- `search` (`string`, optional): Search integrations by name, description, actions, and interfaces. Responses include a matchedOn field indicating which fields matched the search. Example: hubspot
- `sort_by` (`string`, optional): Sort integrations by field. One of: popularity, name, createdAt, updatedAt, installCount. Example: popularity. One of: `popularity`, `name`, `createdAt`, `updatedAt`, `installCount`.
- `verification_status` (`string`, optional): Filter integrations by verification status. One of: unapproved, pending, approved, rejected. Example: unapproved. One of: `unapproved`, `pending`, `approved`, `rejected`.
- `version` (`string`, optional): Integration version. Either a semver version or tag "latest". Example: latest

Example input: `{}`

### `botpress_message_get`

Get Message · Read-only

Get one message with its payload, type, user and tags.
Returns message.
Get the ID from botpress_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Id of the Message. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_messages_list`

List Messages · Read-only

List messages, newest first, optionally for one conversation and date range.
Returns messages, meta.
Pass conversation_id to read one conversation.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `after_date` (`string`, optional): Date in ISO 8601 string with UTC timezone after which the message was created (inclusive) Example: 2026-01-01T00:00:00Z
- `before_date` (`string`, optional): Date in ISO 8601 string with UTC timezone before which the message was created (inclusive) Example: 2026-01-31T23:59:59Z
- `conversation_id` (`string`, optional): Conversation id. Example: conv_01HZX5K9ABCDEF1234567890
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_participants_list`

List Participants · Read-only

List the users taking part in a conversation.
Returns participants, meta.
Get the conversation ID from botpress_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_row_get`

Get Row · Read-only

Get one table row by its numeric ID.
Returns row.
Get the table name or ID from botpress_tables_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`integer`, required): Identifier of the row within the table. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable

Example input: `{"bot_id":"<bot_id>","id":1,"table":"<table>"}`

### `botpress_rows_find`

Find Rows · Read-only

Find table rows with a MongoDB-style filter, text search, column selection, sorting, grouping and paging.
Returns rows, hasMore, offset, limit, warnings.
Use this to query a table. Get the table name or ID from botpress_tables_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable
- `filter` (`object`, optional): Provide a mongodb-like filter to apply to the query. Example: \{ "name": \{ "$eq": "John" \} \}.
- `group` (`object`, optional): Group the rows by a specific column and apply aggregations to them. Allowed values: key, avg, max, min, sum, count. Example: \{ "someId": "key", "orders": ["sum", "avg"] \}.
- `limit` (`integer`, optional): Limit for pagination, specifying the maximum number of rows to return. Example: 20
- `offset` (`integer`, optional): Offset for pagination, specifying where to start returning rows from. Example: 0
- `order_by` (`string`, optional): Specifies the column by which to order the results. By default it is ordered by id. Build-in columns: id, createdAt, updatedAt. Example: createdAt
- `order_direction` (`string`, optional): Specifies the direction of sorting, either ascending or descending. One of: asc, desc. Example: asc. One of: `asc`, `desc`.
- `search` (`string`, optional): Search term to apply to the row search. When using this parameter, some rows which doesn't match the search term will be returned, use the similarity field to know how much the row matches the search term. Example: hubspot
- `select` (`array`, optional): Specify which columns to return in the response. Supports both top-level columns (e.g., "name") and nested attributes using dot notation (e.g., "attributes.price"). System columns (id, createdAt, updatedAt, etc.) are always included. If omitted, all columns are returned. Example: ["email", "score"]

Example input: `{"bot_id":"<bot_id>","table":"<table>"}`

### `botpress_state_get`

Get State · Read-only

Get a named state object for a conversation, user, bot, integration or workflow.
Returns state, meta.
State names are declared in the bot definition.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Id of the State which will be either the botId, the userId or the conversationId. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `name` (`string`, required): Name of the State which is declared inside the bot definition. Example: LeadsTable
- `type` (`string`, required): Represents the resource type that the state is related to. One of: conversation, user, bot, integration, workflow. Example: text. One of: `conversation`, `user`, `bot`, `integration`, `workflow`.

Example input: `{"bot_id":"<bot_id>","id":"<id>","name":"<name>","type":"conversation"}`

### `botpress_table_get`

Get Table · Read-only

Get one table with its schema and row count.
Returns table, rows, stale, indexing.
Get the table name or ID from botpress_tables_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable

Example input: `{"bot_id":"<bot_id>","table":"<table>"}`

### `botpress_tables_list`

List Tables · Read-only

List the tables of a bot.
Returns tables.
Use this to find a table name for the row tools.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_user_get`

Get User · Read-only

Get one end user with name, picture and tags.
Returns user.
Get the ID from botpress_users_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): User ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_users_list`

List Users · Read-only

List the end users who talked to a bot, optionally for one conversation.
Returns users, meta.
Use botpress_user_get for one user.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `after_date` (`string`, optional): Date in ISO 8601 string with UTC timezone after which the user was created or updated (inclusive) Example: 2026-01-01T00:00:00Z
- `before_date` (`string`, optional): Date in ISO 8601 string with UTC timezone before which the user was created or updated (inclusive) Example: 2026-01-31T23:59:59Z
- `conversation_id` (`string`, optional): Filter by conversation id. This will return all users that have participated in the conversation. Example: conv_01HZX5K9ABCDEF1234567890
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20
- `range_field` (`string`, optional): Field used for range filtering. Allowed values are "updatedAt" or "createdAt". Defaults to "createdAt" if omitted. Example: updatedAt. One of: `updatedAt`, `createdAt`.
- `sort_direction` (`string`, optional): Sort results in this direction. One of: asc, desc. Example: asc. One of: `asc`, `desc`.
- `sort_field` (`string`, optional): Sort results by this field. One of: updatedAt, createdAt. Example: updatedAt. One of: `updatedAt`, `createdAt`.

Example input: `{"bot_id":"<bot_id>"}`

### `botpress_workspace_audit_records_list`

List Audit Records · Read-only

List a workspace's audit records, newest first.
Returns records, meta.
Get the ID from botpress_workspaces_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Workspace ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{"id":"<id>"}`

### `botpress_workspace_get`

Get Workspace · Read-only

Get one workspace with its plan, owner and limits.
Returns id, name, ownerId, createdAt, updatedAt, botCount, billingVersion, plan, blocked, spendingLimit.
Get the ID from botpress_workspaces_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Workspace ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"id":"<id>"}`

### `botpress_workspace_members_list`

List Workspace Members · Read-only

List the members of a workspace with their roles.
Returns members, meta.
Use this to see who has access.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{"workspace_id":"<workspace_id>"}`

### `botpress_workspaces_list`

List Workspaces · Read-only

List the workspaces the account belongs to.
Returns workspaces, meta.
Use this to get the workspace ID other admin tools need.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `handle` (`string`, optional): Workspace handle. Example: example
- `next_token` (`string`, optional): Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
- `page_size` (`integer`, optional): Number of items to return per page (default 20, max 100) Example: 20

Example input: `{}`

### `botpress_action_call`

Call Action · Write

Call an action of an integration installed on the bot, for example telegram:sendMessage, with its input object.
Returns output, meta.
Use botpress_hub_integration_get to see an integration's actions and input schema.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `input` (`object`, required): Input of the action. Example: {"conversationId": "conv_01HZX5K9ABCDEF1234567890"}
- `type` (`string`, required): Type of the action. Example: text

Example input: `{"bot_id":"<bot_id>","input":{"conversationId":"conv_01HZX5K9ABCDEF1234567890"},"type":"<type>"}`

### `botpress_bot_create`

Create Bot · Write

Create an empty bot in a workspace with a name, description and tags.
Returns bot.
Build its flows in Botpress Studio afterwards.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
- `description` (`string`, optional): Optional description for the bot. Example: Support bot for the help center
- `name` (`string`, optional): Optional name for the bot, if not provided will be auto-generated. Example: LeadsTable
- `tags` (`object`, optional): Optional attributes of the Bot. Example: {"source": "api"}

Example input: `{"workspace_id":"<workspace_id>"}`

### `botpress_bot_update`

Update Bot · Write

Rename a bot or change its description, tags, blocked or always-alive flags.
Returns bot.
Get the bot ID from botpress_bots_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
- `always_alive` (`boolean`, optional): Indicates if the Bot should be in always alive mode. Example: true
- `blocked` (`boolean`, optional): Blocked. Example: true
- `description` (`string`, optional): Optional description for the bot. Example: Support bot for the help center
- `name` (`string`, optional): Optional name for the bot, if not provided will be auto-generated. Example: LeadsTable
- `tags` (`object`, optional): Optional attributes of the Bot. Set to null or empty string to remove. Example: {"source": "api"}

Example input: `{"id":"<id>","workspace_id":"<workspace_id>"}`

### `botpress_conversation_create`

Create Conversation · Write

Create a conversation on a channel with the tags its integration requires.
Returns conversation.
Most integrations create conversations through their own actions; see botpress_action_call.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `channel` (`string`, required): Channel name. Example: channel
- `tags` (`object`, required): Tags for the Conversation. Example: {"source": "api"}
- `properties` (`object`, optional): EXPERIMENTAL - Optional shared properties that can be accessed and modified by both the bot and any of its integrations. Example: {"plan": "pro"}

Example input: `{"bot_id":"<bot_id>","channel":"<channel>","tags":{"source":"api"}}`

### `botpress_conversation_update`

Update Conversation · Write

Update a conversation's tags or shared properties.
Returns conversation.
Get the conversation ID from botpress_conversations_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `properties` (`object`, optional): EXPERIMENTAL - Optional shared properties that can be accessed and modified by both the bot and any of its integrations. Set individual properties to null to remove them. Example: {"plan": "pro"}
- `tags` (`object`, optional): Tags for the Conversation. Set to null or empty string to remove. Example: {"source": "api"}

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_event_create`

Create Event · Write

Send a custom event to a bot, now or scheduled, optionally linked to a conversation, user, workflow or message.
Returns event.
The event type must be one the bot or an installed integration defines.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `payload` (`object`, required): Payload is the content of the event defined by the integration installed on your bot or one of the default events created by our API. Example: {"text": "Hello from the API"}
- `type` (`string`, required): Type of the Event. Example: text
- `conversation_id` (`string`, optional): ID of the Conversation to link the event to. Example: conv_01HZX5K9ABCDEF1234567890
- `message_id` (`string`, optional): ID of the Message to link the event to. Example: msg_01HZX5K9ABCDEF1234567890
- `schedule` (`object`, optional): Schedule the Event to be sent at a specific time. Either dateTime or delay must be provided. Example: {"delay": 60000}
- `user_id` (`string`, optional): ID of the User to link the event to. Example: user_01HZX5K9ABCDEF1234567890
- `workflow_id` (`string`, optional): ID of the Workflow to link the event to. Example: wf_01HZX5K9ABCDEFGHJKMNPQRSTV

Example input: `{"bot_id":"<bot_id>","payload":{"text":"Hello from the API"},"type":"<type>"}`

### `botpress_file_update`

Update File Metadata · Write

Update a file's tags, access policies or expiry without changing its content.
Returns file.
Get the ID from botpress_files_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): File ID or Key. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `access_policies` (`array`, optional): New access policies to set for the file. Omit to keep existing policies intact. Example: ["integrations"]
- `expires_at` (`string`, optional): Expiry timestamp in ISO 8601 format with UTC timezone. After expiry, the File will be deleted. Must be in the future. Cannot be more than 90 days from now. The value up to minutes is considered. Seconds and milliseconds are ignored. Omit to keep the existing expiry intact. Set to null to remove the expiry. Example: 2026-12-31T00:00:00Z
- `tags` (`object`, optional): The file tags to update as an object of key-value pairs with string (text) values. Omit to keep existing tags intact. Any existing tags not included will be preserved. New tags will be added. To delete a tag, set its value to null. Example: {"source": "api"}

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_message_create`

Create Message · Write

Post a message into a conversation as a user, with a payload such as text, image, choice or card and the tags the integration requires.
Returns message.
Get the conversation and user IDs from botpress_conversations_list and botpress_users_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `conversation_id` (`string`, required): ID of the Conversation. Example: conv_01HZX5K9ABCDEF1234567890
- `payload` (`object`, required): Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location. Example: {"text": "Hello from the API"}
- `tags` (`object`, required): Set of Tags that you can attach to a Message. The set of Tags available on a Message is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them. Example: {"source": "api"}
- `type` (`string`, required): Type of the Message represents the resource type that the message is related to. Example: text
- `user_id` (`string`, required): ID of the User. Example: user_01HZX5K9ABCDEF1234567890
- `origin` (`string`, optional): Origin. One of: synthetic. Example: synthetic. One of: `synthetic`.
- `schedule` (`object`, optional): Schedule the Message to be sent at a specific time. Either dateTime or delay must be provided. Example: {"delay": 60000}

Example input: `{"bot_id":"<bot_id>","conversation_id":"<conversation_id>","payload":{"text":"Hello from the API"},"tags":{"source":"api"},"type":"<type>","user_id":"<user_id>"}`

### `botpress_message_update`

Update Message · Write

Update a message's payload or tags. Its type cannot change.
Returns message.
Get the ID from botpress_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Message id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `payload` (`object`, optional): Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location. Example: {"text": "Hello from the API"}
- `tags` (`object`, optional): Set of Tags that you can attach to a Message. The set of Tags available on a Message is restricted by the list of Tags defined previously by the Bot. Set to null or empty string to remove. Example: {"source": "api"}

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_participant_add`

Add Participant · Write

Add a user to a conversation.
Returns participant.
Get the user ID from botpress_users_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `user_id` (`string`, required): User id. Example: user_01HZX5K9ABCDEF1234567890

Example input: `{"bot_id":"<bot_id>","id":"<id>","user_id":"<user_id>"}`

### `botpress_rows_create`

Create Rows · Write

Insert one or more rows into a table.
Returns rows, warnings, errors.
Use botpress_rows_upsert to insert or update by key. Get the table name or ID from botpress_tables_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `rows` (`array`, required): Rows. Example: [{"email": "jane@example.com", "score": 42}]
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable
- `wait_computed` (`boolean`, optional): Ensure computed columns are fully processed before returning the result. This is applicable only when the number of rows involved is fewer than 1. Example: true

Example input: `{"bot_id":"<bot_id>","rows":[{"email":"jane@example.com","score":42}],"table":"<table>"}`

### `botpress_rows_update`

Update Rows · Write

Update rows by ID. Each row object carries its id plus the columns to change.
Returns rows, warnings, errors.
Get row IDs from botpress_rows_find.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `rows` (`array`, required): Rows with updated data, identified by ID. Example: [{"id": 1, "score": 50}]
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable
- `wait_computed` (`boolean`, optional): Ensure computed columns are fully processed before returning the result. This is applicable only when the number of rows involved is fewer than 1. Example: true

Example input: `{"bot_id":"<bot_id>","rows":[{"id":1,"score":50}],"table":"<table>"}`

### `botpress_rows_upsert`

Upsert Rows · Write

Insert rows, or update existing ones that match on a key column.
Returns inserted, updated, warnings, errors.
Get the table name or ID from botpress_tables_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `rows` (`array`, required): Rows. Example: [{"email": "jane@example.com", "score": 42}]
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable
- `key_column` (`string`, optional): Determines if a row is inserted or updated. Defaults to "id". Example: email
- `wait_computed` (`boolean`, optional): Ensure computed columns are fully processed before returning the result. This is applicable only when the number of rows involved is fewer than 1. Example: true

Example input: `{"bot_id":"<bot_id>","rows":[{"email":"jane@example.com","score":42}],"table":"<table>"}`

### `botpress_state_set`

Set State · Write

Replace a named state object with a new payload, optionally expiring after idle time.
Returns state.
Use botpress_state_get to read it first.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Id of the State which will be either the botId, the userId or the conversationId. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `name` (`string`, required): Name of the State which is declared inside the bot definition. Example: LeadsTable
- `payload` (`object`, required): Payload is the content of the state defined by your bot. Example: {"text": "Hello from the API"}
- `type` (`string`, required): Represents the resource type that the state is related to. One of: conversation, user, bot, integration, workflow. Example: text. One of: `conversation`, `user`, `bot`, `integration`, `workflow`.
- `expiry` (`number`, optional): Expiry of the State in milliseconds. The state will expire if it is idle for the configured value. By default, a state doesn't expire. Example: 3600000

Example input: `{"bot_id":"<bot_id>","id":"<id>","name":"<name>","payload":{"text":"Hello from the API"},"type":"conversation"}`

### `botpress_table_column_rename`

Rename Table Column · Write

Rename a column in a table.
Returns table.
Get the table name or ID from botpress_tables_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `name` (`string`, required): The existing name of the column. Example: LeadsTable
- `new_name` (`string`, required): The new name to assign to the column. Example: email_address
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable

Example input: `{"bot_id":"<bot_id>","name":"<name>","new_name":"<new_name>","table":"<table>"}`

### `botpress_table_create`

Create Table · Write

Create a table from a JSON schema of columns (up to 20), with optional key column and tags.
Returns table.
Use botpress_rows_create to add rows.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `name` (`string`, required): Required. This name is used to identify your table. Example: LeadsTable
- `schema` (`object`, required): Provide an object or a JSON schema to define the columns of the table. A maximum of 20 keys in the object/schema is allowed. Example: {"type": "object", "properties": {"email": {"type": "string"}, "score": {"type": "number"}}}
- `factor` (`number`, optional): The 'factor' multiplies the row's data storage limit by 4KB and its quota count. It can only be increased (not decreased) after table creation via updateTable. For instance, a factor of 2 increases storage to 8KB but counts as 2 rows in your quota. The default factor is 1. Example: 1
- `frozen` (`boolean`, optional): A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations. Example: true
- `is_compute_enabled` (`boolean`, optional): Indicates if the table is enabled for computation. Example: true
- `key_column` (`string`, optional): Designate a column as the primary unique identifier for this table. When set, a unique index is automatically created on this column, enabling significantly faster upsert operations. All values in this column must be unique across the table. When set to null, the key index is removed. Example: email
- `tags` (`object`, optional): Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs. Example: {"source": "api"}

Example input: `{"bot_id":"<bot_id>","name":"<name>","schema":{}}`

### `botpress_table_update`

Update Table · Write

Rename a table or change its schema, key column, frozen flag or tags.
Returns table, staleColumns, job.
Get the table name or ID from botpress_tables_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable
- `factor` (`number`, optional): The 'factor' multiplies the row's data storage limit by 4KB and its quota count. It can only be increased, not decreased. For instance, a factor of 2 increases storage to 8KB but counts as 2 rows in your quota. Example: 10
- `frozen` (`boolean`, optional): A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations. Example: true
- `is_compute_enabled` (`boolean`, optional): Indicates if the table is enabled for computation. Example: true
- `key_column` (`string`, optional): Designate a column as the primary unique identifier for this table. When set, a unique index is automatically created on this column, enabling significantly faster upsert operations. All values in this column must be unique across the table. When set to null, the key index is removed. Example: email
- `name` (`string`, optional): Required. This name is used to identify your table. Example: LeadsTable
- `schema` (`object`, optional): Provide an object or a JSON schema to define the columns of the table. A maximum of 20 keys in the object/schema is allowed. Example: {"type": "object", "properties": {"email": {"type": "string"}, "score": {"type": "number"}}}
- `tags` (`object`, optional): Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs. Example: {"source": "api"}

Example input: `{"bot_id":"<bot_id>","table":"<table>"}`

### `botpress_user_create`

Create User · Write

Create an end user with the tags its integration requires, plus a name and picture.
Returns user.
Use botpress_user_update to change one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `tags` (`object`, required): Tags for the User. Example: {"source": "api"}
- `name` (`string`, optional): Name of the user. Example: LeadsTable
- `picture_url` (`string`, optional): URI of the user picture. Example: https://example.com/avatar.png
- `properties` (`object`, optional): EXPERIMENTAL - Optional shared properties that can be accessed and modified by both the bot and any of its integrations. Example: {"plan": "pro"}

Example input: `{"bot_id":"<bot_id>","tags":{"source":"api"}}`

### `botpress_user_update`

Update User · Write

Update an end user's name, picture, tags or shared properties.
Returns user.
Get the ID from botpress_users_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): User ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `name` (`string`, optional): Name of the user. Example: LeadsTable
- `picture_url` (`string`, optional): URI of the user picture. Example: https://example.com/avatar.png
- `properties` (`object`, optional): EXPERIMENTAL - Optional shared properties that can be accessed and modified by both the bot and any of its integrations. Set individual properties to null to remove them. Example: {"plan": "pro"}
- `tags` (`object`, optional): Tags for the User. Set to null or empty string to remove. Example: {"source": "api"}

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_bot_delete`

Delete Bot · Destructive

Delete a bot and its data.
Get the bot ID from botpress_bots_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `workspace_id` (`string`, required): ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890

Example input: `{"id":"<id>","workspace_id":"<workspace_id>"}`

### `botpress_conversation_delete`

Delete Conversation · Destructive

Delete a conversation and its messages.
Get the conversation ID from botpress_conversations_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_file_delete`

Delete File · Destructive

Delete a file.
Get the ID from botpress_files_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): File ID or Key. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_message_delete`

Delete Message · Destructive

Delete a message.
Get the ID from botpress_messages_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Message id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

### `botpress_participant_remove`

Remove Participant · Destructive

Remove a user from a conversation.
Get the conversation ID from botpress_conversations_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `user_id` (`string`, required): User id. Example: user_01HZX5K9ABCDEF1234567890

Example input: `{"bot_id":"<bot_id>","id":"<id>","user_id":"<user_id>"}`

### `botpress_rows_delete`

Delete Rows · Destructive

Delete rows by ID, by filter, or all rows of a table.
Returns deletedRows, job.
Deleting by filter runs in the background. Get the table name or ID from botpress_tables_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable
- `delete_all_rows` (`boolean`, optional): Flag to delete all rows. Use with caution as this action is irreversible. Example: true
- `filter` (`object`, optional): Filter to apply when deleting rows. Deletion with a filter is performed asynchronously in batches and returns a job object to track progress. Example: \{ "createdAt": \{ "$lt": "2026-01-01" \} \}.
- `ids` (`array`, optional): IDs. Example: [1, 2]

Example input: `{"bot_id":"<bot_id>","table":"<table>"}`

### `botpress_table_delete`

Delete Table · Destructive

Delete a table and all its rows.
Get the table name or ID from botpress_tables_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `table` (`string`, required): The table's name or unique identifier for targeting specific table operations. Example: LeadsTable

Example input: `{"bot_id":"<bot_id>","table":"<table>"}`

### `botpress_user_delete`

Delete User · Destructive

Delete an end user.
Get the ID from botpress_users_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bot_id` (`string`, required): ID of the Botpress bot to act on, sent in the x-bot-id header. Get it from botpress_bots_list or the bot's URL in Botpress Studio. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
- `id` (`string`, required): User ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0

Example input: `{"bot_id":"<bot_id>","id":"<id>"}`

## Related

Other AI connectors ([all 216](/agentkit/connectors/?category=ai)):

- [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools
- [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 69 tools
- [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
