• Public
  • Public/Protected
  • All

Module "botpress/sdk"

Botpress SDK

Botpress SDK allows you to create Botpress Modules that extends the functionalities of the platform. Botpress SDK exposes all the major methods that a Module needs to interact with the core.

We made sure that the SDK is always up-to-date with the latest version of Botpress. It will always match the current version of your Botpress installation.

Tip: For step-by-step instructions in how to install a Module or create one, see our Developer's Guide Module Section.

How to use Botpress SDK

To use the SDK in your Module, it has to be recognized by Botpress.

Tip: Before continuing, please refer to the Module Building section of our Developer's Guide to learn how to build your Module.

Definition File

The Botpress SDK definition file (botpress.d.ts) can be either copied manually from src/bp/sdk/botpress.d.ts or copied automatically while running the yarn build:modules in your project root.

Once you have the definition file ready, you can import it with import sdk from 'botpress/sdk' and use it in your code.

Example usage

import sdk from 'botpress/sdk'


async function sendNewMessage(botId, userId, conversationId, payload) {
  const event = sdk.IO.Event({
    channel: 'web',
    direction: 'incoming',
    target: userId,
    threadId: conversationId,
    type: payload.type

  const message = await this.db.appendUserMessage(botId, userId, conversationId, persistedPayload)

  sdk.realtime.sendPayload(sdk.RealTimePayload.forVisitor(userId, 'webchat.message', message))
  return sdk.events.sendEvent(event)

Quick Start Module

You can use our quick-start-module if you want to play around with the SDK in an empty Module.

Build the SDK Reference

From the project root, run yarn build:reference. This will copy the static assets into docs/reference/public/.


Our goal is to make sure that Botpress SDK is always well documented. If you find things you can improve or clarify, feel free to contribute to the Botpress SDK definition file.


Type aliases


BotConfig: object

The configuration definition of a bot.

Type declaration

  • Optional $schema?: undefined | string
  • Optional author?: undefined | string
  • Optional category?: undefined | string
  • Optional converse?: ConverseConfig
  • defaultLanguage: string
  • Optional description?: undefined | string
  • details: BotDetails
  • Optional dialog?: DialogConfig
  • Optional disabled?: undefined | false | true
  • id: string
  • imports: object
    • contentTypes: string[]

      Defines the list of content types supported by the bot

  • languages: string[]
  • locked: boolean
  • Optional logs?: LogsConfig
  • name: string
  • Optional oneflow?: undefined | false | true
  • pipeline_status: BotPipelineStatus
  • Optional private?: undefined | false | true
  • version: string


ContentType: object

A Content Type describes a grouping of Content Elements @see ContentElement sharing the same properties. They can describe anything and everything – they most often are domain-specific to your bot. They also tells botpress how to display the content on various channels

Type declaration

  • Optional computePreviewText?: undefined | function

    Function that computes the visual representation of the text. This function resides in the javascript definition of the Content Type.

  • description: string
  • hidden: boolean

    Hiding content types prevents users from adding these kind of elements via the Flow Editor. They are still visible in the Content Manager, and it's still possible to use these elements by specifying their name as a property "contentType" to ContentPickerWidget.

  • id: string
  • jsonSchema: object

    The jsonSchema used to validate the form data of the Content Elements.

  • renderElement: function

    Function that defines how a Content Type gets rendered on different channels. This function resides in the javascript definition of the Content Type.


    The data required to render the Content Elements. e.g. Text, images, button actions, etc.


    The channel used to communicate, e.g. channel-web, messenger, twilio, etc.


    Return an array of rendered Content Elements

      • (data: object, channel: string): any[]
      • Parameters

        • data: object
        • channel: string

        Returns any[]

  • title: string
  • Optional uiSchema?: undefined | object


ConverseConfig: object

Configuration file definition for the Converse API

Type declaration

  • maxMessageLength: number

    The text limitation of the converse API requests



  • timeout: string

    The timeout of the converse API requests




ElementChangedAction: "create" | "update" | "delete"


EventDirection: "incoming" | "outgoing"

The direction of the event. An incoming event will register itself into the incoming middleware chain. An outgoing event will register itself into the outgoing middleware chain.


MiddlewareDefinition to learn more about middleware.


EventSearchParams: object

Type declaration

  • Optional count?: undefined | number
  • Optional from?: undefined | number

    Returns the amount of elements from the starting position

  • Optional sortOrder?: SortOrder[]

    An array of columns with direction to sort results


FlowNode: object & NodeActions


FlowNodeType: "standard" | "skill-call" | "listen" | "say_something" | "success" | "failure" | "trigger" | "execute" | "router" | "action"


GetOrCreateResult: Promise<object>


KnexExtended: Knex & KnexExtension


ListenNode: FlowNode & object


Notification: object

Type declaration

  • botId: string
  • level: string

    Can be info, error, success

  • message: string
  • Optional moduleIcon?: undefined | string
  • Optional moduleId?: undefined | string
  • Optional moduleName?: undefined | string
  • Optional redirectUrl?: undefined | string

    An URL to redirect to when the notification is clicked


Pipeline: Stage[]


RolloutStrategy: "anonymous" | "anonymous-invite" | "authenticated" | "authenticated-invite" | "authorized"

All available rollout strategies (how users interact with bots of that workspace) An invite code is permanent, meaning that it will be consumed once and will not be necessary for that user in the future

anonymous: Anyone can talk to bots anonymous-invite: Anyone with an invite code can talk to bots authenticated: Authenticated users will be automatically added to workspace as "chat user" (will then be "authorized") authenticated-invite: Authenticated users with an invite code will be added to workspace as "chat user" (will then be "authorized") authorized: Only authenticated users with an existing access to the workspace can talk to bots


RouterCondition: boolean | function


RouterOptions: object

Those are possible options you may enable when creating new routers

Type declaration

  • checkAuthentication: RouterCondition

    Check if user is authenticated before granting access



  • Optional checkMethodPermissions?: RouterCondition

    When checkAuthentication is enabled, set this to true to enforce permissions based on the method. GET/OPTIONS requests requires READ permissions, while all other requires WRITE permissions



  • Optional enableJsonBodyParser?: RouterCondition

    Parse the body as JSON when possible



  • Optional enableUrlEncoderBodyParser?: RouterCondition

    Only parses body which are urlencoded




SearchParams: object

Search parameters when querying content elements

Type declaration

  • count: number
  • Optional filters?: Filter[]

    Apply a filter to a specific field (instead of the 'search all' field)

  • from: number

    Returns the amount of elements from the starting position

  • Optional ids?: string[]

    Only returns the items matching these ID

  • Optional searchTerm?: undefined | string

    Search in elements id and form data

  • Optional sortOrder?: SortOrder[]

    An array of columns with direction to sort results


SkillFlow: Partial<Flow> & Pick<Required<Flow>, "nodes">

The partial flow is only used to make some nodes optional. Those left empty will be automatically generated by the skill service.


SkillFlowNode: Partial<ListenNode> & Pick<Required<ListenNode>, "name"> & Partial<TriggerNode>


StageAction: "promote_copy" | "promote_move"


State: any

A state is a mutable object that contains properties used by the dialog engine during a conversation. Properties like "nickname" or "nbOfConversations" are used during a conversation to execute flow logic. e.g. Navigating to a certain node when a condition is met.


StrategyUser: object & UserInfo


TriggerNode: FlowNode & object


User: object

Type declaration

  • attributes: any
  • channel: string
  • createdOn: Date
  • id: string
  • Optional otherChannels?: User[]
  • updatedOn: Date


Const database

database: KnexExtended

This variable gives you access to the Botpress database via Knex. When developing modules, you can use this to create tables and manage data



Const logger

logger: Logger

The logger instance is automatically scoped to the calling module


bp.logger.info('Hello!') will output: Mod[myModule]: Hello!

Const version

version: string

Returns the current version of Botpress

Generated using TypeDoc