​
1. Install The Botpress CLI

To get started, first install the Botpress CLI globally on your machine. You can do this by running the following command in your terminal:

npm install -g @botpress/cli
All the following examples use npm, but feel free to use the package manager of your choice like yarn or pnpm.

You can check that your installation was successful by running the following command:

bp --help

​
2. Log in to Botpress

Next, log in to your Botpress account using the Botpress CLI. You can do this by running the following command in your terminal:

bp login

This command will prompt you for a personal access token. You can create a new token by going to the Dashboard and navigating to the Personal Access Tokens page.

​
3. Initialize a New Integration

Next, create a new integration using the Botpress CLI. This will set up a new directory with the necessary files and structure for your integration.

bp init --type "integration" --name "my-integration" --template "hello-world"

The CLI will prompt you for some information, including your Workspace or Workspace handle. If you don’t have a Workspace handle yet, the CLI should claim one for you. You can also claim one manually by going to the Dashboard and navigating to the Settings page.

​
4. Install Dependencies and Build

Once the integration is initialized, navigate to the integration directory and install the dependencies:

cd ./my-integration
npm i
bp build

​
5. Browse the Integration Files

You can now open the integration in VS Code or another code editor of your choice:

code .

Here’s a brief overview of the files and folders you’ll find in the integration directory:

  • integrations.definition.ts: Contains the integration definition. It exports a data structure that describes your integration—what it is, what it can do, and how it can be used. This includes the integration’s name, version, actions, events, channels, and other capabilities. The template you chose declares a single action, helloWorld, which accepts an optional name parameter and returns a greeting message. Keep reading this documentation to learn about all the concepts you can define in this file.

  • src/index.ts: Contains the integration implementation. It exports a data structure that implements what was defined in the integration definition. Keep reading this documentation to learn about the available callbacks you can implement.

  • .botpress/: Contains the integration output, generated by the build command. It includes typings to help you implement your integration, and bundled JavaScript used to execute it. You can explore its contents, but avoid importing from nested files or folders, as its structure may change. Everything meant to be imported is available from the root of this folder.

  • icon.svg, hub.md: These files contain the integration’s icon and README. They are referenced in the integration definition.

  • package.json, tsconfig.json: As with any Node.js TypeScript project, these files contain your package’s metadata and dependencies, and the TypeScript configuration. The tsconfig.json file is preconfigured to offer the best experience with the Botpress SDK. Run npm run check:type to check for typing errors.

​
6. Update the Code to Remove Errors

The template you chose ships with unimplemented register callbacks. In src/index.ts, you’ll see register and unregister functions with a body that looks like this:

throw new sdk.RuntimeError('Invalid configuration')

Remove these error statements for now. You can come back later to implement your own validation logic.

​
7. Deploy the Integration

Once you’ve made the necessary changes to your integration, you can deploy it to Botpress Cloud. Run the following command:

bp deploy

You’ll be prompted for some information and confirmations. This integration will be deployed privately to your Workspace, and will only be visible and usable by members of your Workspace. As long as it remains private, you can update the same version by running the deploy command again. To deploy a new version, update the integration definition and run the deploy command once more.

After deploying, go to the Dashboard and navigate to the Your Integrations page. You should see your integration listed there.

​
8. Try Out Your Integration in Botpress Studio

Now you can test your integration:

  1. Create a new bot or open an existing one in Botpress Studio.
  2. Navigate to Botpress Hub and install your integration.
  3. Create a basic Workflow and use the helloWorld Card. It will return a greeting message.

​
What’s Next?

For a better guide on how to integrate your integration with external messaging channels, check out the Integration for Messaging Channels page.

For a more in-depth explanation of integration definition concepts, check out the Integration Concepts page.