Required dependencies

npm install @botpress/sdk @botpress/sdk-addons @botpress/cli
npm install @botpress/common
npm install @anthropic-ai/sdk          # required by anthropic/
npm install @sentry/node               # required by integrations using sentry helpers

The @botpress/cli toolchain compiles each integration. There is no native (iOS/Android) build step. Each integration is deployed via:

bp deploy

from within the integration's own directory.

Project setup

1. Install the Botpress CLI globally:

   npm install -g @botpress/cli
   

2. Copy the desired integration folder (e.g., source/airtable/) into your project or a monorepo workspace.

3. Install dependencies inside the integration directory:

   cd airtable
   npm install
   

4. Wire tsconfig.json - each integration ships its own tsconfig.json. The generated .botpress/ types folder (produced by bp generate) must be present before building:

   bp generate   # produces .botpress/ with typed client, secrets, etc.
   npm run build
   

5. Set environment / secret variables. Each integration reads secrets via the generated bp.secrets object. Declare them in integration.definition.ts under secrets: and supply values in the Botpress Cloud dashboard or via .env for local testing.

6. Deploy:

   bp deploy                        # private to your workspace
   bp deploy --visibility public    # publish to Botpress Hub
   

Public API

new bp.Integration(props)

import * as bp from '.botpress'

const integration = new bp.Integration({
  register:   async ({ client, ctx, logger }) => void,
  unregister: async ({ client, ctx, logger }) => void,
  actions:    Record<string, ActionHandler>,
  channels:   Record<string, ChannelDefinition>,
  handler:    async ({ req, client, ctx, logger }) => void,
})

export default integration

The primary constructor for any Botpress integration. register runs on installation, unregister on removal, actions maps action names to handlers, channels defines messaging surfaces, and handler processes inbound HTTP events from the third-party platform.

bp.secrets

// Accessed at module level in each integration
const apiKey: string = bp.secrets.MY_API_KEY

A typed, generated object that exposes all secrets declared in integration.definition.ts. Secrets are injected at runtime by the Botpress Cloud runtime; never hardcode credentials. Declare a new secret in integration.definition.ts then re-run bp generate.

sentryHelpers.wrapIntegration

import { sentry as sentryHelpers } from '@botpress/sdk-addons'
import * as bp from '.botpress'

const wrapped = sentryHelpers.wrapIntegration(integration, {
  dsn:         bp.secrets.SENTRY_DSN,
  environment: bp.secrets.SENTRY_ENVIRONMENT,
  release:     bp.secrets.SENTRY_RELEASE,
})

export default wrapped

Wraps an Integration instance so that unhandled exceptions in any action or handler are automatically captured and forwarded to Sentry. Use this in any production integration where observability matters. The three secrets (SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE) must be declared in integration.definition.ts.

Working examples

Scenario - Register an Airtable connection and expose read/write actions

Copy source/airtable/ into your monorepo. The integration authenticates against Airtable on install and exposes six typed actions.

// airtable/src/index.ts (verbatim pattern)
import actions from './actions'
import { AirtableApi } from './client'
import * as botpress from '.botpress'

export default new botpress.Integration({
  register: async ({ client, ctx, logger }) => {
    const airtableClient = new AirtableApi({ client, ctx, logger })
    await airtableClient.testConnection()
    logger.forBot().info('Connection to Airtable successful')
  },
  unregister: async () => {},
  actions,
  channels: {},
  handler: async () => {},
})

The actions export includes getTableRecords, createTable, updateTable, createRecord, updateRecord, and listRecords.

Scenario - Expose Anthropic Claude with reasoning-mode control

// anthropic/src/index.ts usage pattern
import Anthropic from '@anthropic-ai/sdk'
import * as bp from '.botpress'
import { ThinkingModeBudgetTokens, ReasoningModelIdReplacements } from './index'

// ThinkingModeBudgetTokens maps effort level → budget tokens
const budgetTokens = ThinkingModeBudgetTokens['medium'] // 8192

// ReasoningModelIdReplacements remaps deprecated reasoning model IDs
const resolvedModel =
  ReasoningModelIdReplacements['claude-sonnet-4-reasoning-20250514']
  ?? 'claude-sonnet-4-reasoning-20250514'

const client = new Anthropic({ apiKey: bp.secrets.ANTHROPIC_API_KEY })

Use ThinkingModeBudgetTokens to control how many tokens Claude may spend on internal chain-of-thought reasoning before producing a visible response.

Scenario - Wrap an integration with Sentry error tracking (Asana pattern)

import { sentry as sentryHelpers } from '@botpress/sdk-addons'
import actions from './actions'
import { register, unregister, channels, handler } from './setup'
import * as bp from '.botpress'

const integration = new bp.Integration({
  register,
  unregister,
  actions,
  channels,
  handler,
})

export default sentryHelpers.wrapIntegration(integration, {
  dsn:         bp.secrets.SENTRY_DSN,
  environment: bp.secrets.SENTRY_ENVIRONMENT,
  release:     bp.secrets.SENTRY_RELEASE,
})

Any action that throws an unhandled error will be reported to Sentry before the Botpress runtime receives the failure.

File walkthrough

• airtable/integration.definition.ts - Declares the integration's identity, secrets, and typed action schemas consumed by bp generate.
• airtable/src/index.ts - Entry point; constructs and exports the Integration instance with register/unregister/actions/handler.
• airtable/src/actions/index.ts - Re-exports all action handler functions as a single object satisfying bp.IntegrationProps['actions'].
• airtable/src/client.ts - AirtableApi class wrapping the Airtable REST API; injected with Botpress client, ctx, and logger.
• anthropic/src/index.ts - Instantiates the Anthropic SDK, defines model catalogue (LanguageModels), reasoning budget map, and model-ID remapping table.
• asana/src/index.ts - Demonstrates the Sentry-wrapped pattern; delegates register, channels, and handler to a setup module.
• asana/src/actions/index.ts - Exports createTask, updateTask, findUser, addCommentToTask.
• airtable/hub.md - Markdown shown on the Botpress Hub listing for the integration.
• airtable/icon.svg - Integration icon displayed in the Botpress Studio.
• airtable/package.json - Per-integration npm manifest; dependencies are kept minimal and integration-specific.
• airtable/tsconfig.json - TypeScript config extending the workspace base; paths resolve .botpress/ generated types.
• airtable/vitest.config.ts - Vitest configuration for unit-testing action handlers in isolation.

Common pitfalls and fixes

• .botpress/ types missing at compile time - Run bp generate before tsc or npm run build; the generated folder is not committed to source control.
• bp.secrets.* is undefined at runtime - Secrets must be declared in integration.definition.ts and populated in the Botpress Cloud dashboard; a missing declaration silently produces undefined.
• ESM/CJS interop with @anthropic-ai/sdk - Set "moduleResolution": "bundler" or "node16" in tsconfig.json; the Anthropic SDK ships ESM-first.
• Sentry secrets not declared - If you copy the Asana pattern, add SENTRY_DSN, SENTRY_ENVIRONMENT, and SENTRY_RELEASE to integration.definition.ts under secrets; omitting any one causes a runtime type error.
• bp deploy --visibility public is irreversible - Once a version is published to the Hub it cannot be edited; always test with a private deploy first.
• Action handler type mismatch - The actions object must satisfy bp.IntegrationProps['actions'] exactly (use as const satisfies ... as shown in airtable/src/actions/index.ts) to catch schema drift at compile time.

Vibe-coding prompt template

I have a copy of the Botpress Cloud Integrations source in the `source/` directory.
I also have the full usage guide in `USAGE.md`.

My project is a Node.js/TypeScript backend. I want to integrate the
[INTEGRATION_NAME] integration (located at `source/[integration-name]/`)
into my existing project.

Please help me do the following, step by step:

1. Read `source/[integration-name]/integration.definition.ts` and explain
   every secret and action it declares.
2. Run `bp generate` inside `source/[integration-name]/` to produce the
   `.botpress/` typed layer, then walk me through the generated types.
3. Show me how to instantiate the Integration using `new bp.Integration({...})`
   with real `register`, `actions`, and `handler` implementations.
4. Wire up any required secrets in my local `.env` and show me the
   `integration.definition.ts` secret declaration block.
5. Show me how to call each exported action (e.g., `createRecord`,
   `listRecords`) from a bot flow or external script using the Botpress client.
6. If this integration supports Sentry, wrap it with
   `sentryHelpers.wrapIntegration` as shown in `USAGE.md`.
7. Produce a working `src/index.ts` I can deploy with `bp deploy`.

Use only the real exports visible in `source/` and documented in `USAGE.md`.
Do not invent API methods.

License and credit

The source is part of the botpress/botpress monorepo. See source/LICENSE if present, or refer to the repository's root license (MIT as of the last public release). Upstream package: @botpress/sdk on npm. CLI: @botpress/cli on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Claude TypeScript SDK for Multiple Cloud Platforms

SaaS, AI & Subscription Products

Free