• Public
  • Public/Protected
  • All

Module "botpress/sdk"

Botpress SDK

Botpress SDK allows you to create Botpress Modules that extends the functionnalities of the plateform. 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
  • active: boolean
  • Optional author?: undefined | string
  • Optional description?: undefined | string
  • Optional dialog?: DialogConfig
  • id: string
  • imports: object
    • contentTypes: string[]

      Defines the list of content types supported by the bot

  • Optional logs?: LogsConfig
  • name: string
  • 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
  • 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


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.


FlowNode: object & NodeActions


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


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



  • enableJsonBodyParser: RouterCondition

    Parse the body as JSON when possible




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<FlowNode> & Pick<Required<FlowNode>, "name">


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.


User: object

Type declaration

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


Const database

database: any

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