Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Botpress

Scalekit connector
Open markdown

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.

Tools
58
What they doRead · write · destructive
31 · 19 · 831 read19 write8 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

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

  4. Authorize a user and make your first call

    quickstart.mts
    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)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Botpress credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • botpress_account_getGet the Botpress account that owns the personal access token.Read-only

    Get Account

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

    Inputs

    This tool takes no inputs.

  • botpress_bot_analytics_getGet a bot's usage analytics (users, sessions, messages, LLM calls) for a date range.Read-only

    Get Bot Analytics

    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.

    Inputs

    end_datestringrequired
    End date/time (inclusive) Example: 2026-01-31T23:59:59Z
    idstringrequired
    Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
    start_datestringrequired
    Start date/time (inclusive) Example: 2026-01-01T00:00:00Z
    workspace_idstringrequired
    ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
  • botpress_bot_getGet one bot's definition, integrations, status and settings.Read-only

    Get Bot

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

    Inputs

    idstringrequired
    Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
    workspace_idstringrequired
    ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
  • botpress_bot_issue_getGet one bot issue with its category, count and last occurrence.Read-only

    Get Bot Issue

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

    Inputs

    idstringrequired
    Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
    issue_idstringrequired
    Issue ID. Example: iss_01HZX5K9ABCDEF
    workspace_idstringrequired
    ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
  • botpress_bot_issues_listList the runtime issues (errors) recorded for a bot.Read-only

    List Bot Issues

    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.

    Inputs

    idstringrequired
    Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
    workspace_idstringrequired
    ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
    next_tokenstring
    Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
    page_sizeinteger
    Number of items to return per page (default 20, max 100) Example: 20
  • botpress_bot_logs_getGet a bot's logs for a time range, filterable by level, user, workflow, conversation or text.Read-only

    Get Bot Logs

    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.

    Inputs

    idstringrequired
    Bot ID. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0
    time_startstringrequired
    Beginning of the time range to get logs from. Example: 2026-01-15T00:00:00Z
    workspace_idstringrequired
    ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
    conversation_idstring
    Filter by conversation ID. Example: conv_01HZX5K9ABCDEF1234567890
    levelstring
    Filter by log level. Example: error
    message_containsstring
    Filter logs where the message contains this substring. Example: timeout
    next_tokenstring
    Token to get the next page of logs. Example: eyJsYXN0SWQiOiJhYmMifQ
    time_endstring
    End of the time range to get logs from. Example: 2026-01-15T23:59:59Z
    user_idstring
    Filter by user ID. Example: user_01HZX5K9ABCDEF1234567890
    workflow_idstring
    Filter by workflow ID. Example: wf_01HZX5K9ABCDEFGHJKMNPQRSTV
  • botpress_bots_listList the bots in a workspace, production or dev, optionally by installed integrations.Read-only

    List Bots

    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.

    Inputs

    workspace_idstringrequired
    ID of the Botpress workspace, sent in the x-workspace-id header. Get it from botpress_workspaces_list. Example: wkspace_01HZX5K9ABCDEF1234567890
    devboolean
    If true, only dev bots are returned. Otherwise, only production bots are returned. Example: true
    integration_namesarray
    Filter bots that have ALL of these integrations installed (by definition name) Example: ["value"]
    next_tokenstring
    Provide the meta.nextToken value provided in the last API response to retrieve the next page of results. Example: eyJsYXN0SWQiOiJhYmMifQ
    page_sizeinteger
    Number of items to return per page (default 20, max 100) Example: 20
    plugin_namesarray
    Filter bots that have ALL of these plugins installed (by definition name) Example: ["value"]
    sort_directionstring
    Sort results in this direction. One of: asc, desc. Example: ascone of ascdesc
    sort_fieldstring
    Sort results by this field. One of: createdAt, updatedAt. Example: createdAtone of createdAtupdatedAt
  • botpress_conversation_getGet one conversation with its channel, integration and tags.Read-only

    Get Conversation

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

    Inputs

    bot_idstringrequired
    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
    idstringrequired
    Conversation id. Example: 8f1c2a9e-4b0a-41b2-93d4-e5f6a7b8c9d0