What are Botpress Integrations?

Integrations in Botpress are an easy and powerful way to extend Botpress channels, or improve the bot building experience.

Integrations have three main capabilities:

1. Connecting bots with messaging channels (e.g. Telegram, Facebook Messenger)
2. Extending Botpress Studio to add action cards that run any NodeJS code. (e.g. send an email, create a Jira ticket)
3. Extending Botpress Studio by adding event listeners, invokable by adding triggers. (e.g. get notified when a purchase is made)

They can be shared privately, or published to the Botpress Hub, where they can be discovered and installed by every Botpress user. They also run free of charge on Botpress Infrastructure, so you don't have to worry about hosting, scaling or even cost issues!

Setting up your first integration

You can simply follow the instructions below.

Prerequisites

• A workspace with a bot in Botpress Cloud
• Your workspace handle must be set. You can do so by going to your your workspace, clicking "Settings", and setting your workspace handle.
• A valid ngrok authentication token. Please see the following steps to obtain one:
  • 1. Create an account on https://ngrok.com
    2. Get your auth token from https://dashboard.ngrok.com/get-started/setup
    3. Run in your terminal: npx ngrok config add-authtoken YOUR_TOKEN

🚧

Windows users

We recommend you use WSL2 for building your integration. You will encounter issues on non-unix based systems.

Installing the integration to your workspace

Create a new integration project using the init command. This will create a new folder with the name you specified and generate a basic project structure.

1. Change my-integration with the name of your integration (no spaces), and run the following command.

INTEGRATION_NAME=my-integration
npx @botpress/cli init --name $INTEGRATION_NAME --type integration
cd $INTEGRATION_NAME
npm i --save-dev @growth-botpress/bp-integration-runner
npm i

bp-integration-runner allows you to easily run the integration locally, with hot-reloading and the ability to view logs locally.

2. Now add this script to your package.json file:

{
  ...,
  "scripts": {
    "dev-local": "bp-integration-runner"
  },
  ...
}

Make sure to replace your package.json has an integrationName parameter such as my-integration with your integration name. The name is used as an id in combination with your workspace. It is not the display title for the integration, which is found in integration.definition.ts

3. Create a .env file which will contain your Botpress Personal Access Token and a Workspace ID to run your integration in dev mode. You can create an access token by visiting your Botpress Cloud Profile Page and clicking "Generate new token".

BOTPRESS_PAT=YOUR_PERSONAL_ACCESS_TOKEN
BOTPRESS_WORKSPACE_ID=YOUR_WORKSPACE_ID

We're now done with setup. We suggest you commit your repo at this point.

4. Create a .gitignore file in the root folder with the following content:

.botpress
node_modules/

Now you can start developing your integration.

5. You can run the following command to start developing your integration:

npm run dev-local

6. When your integration is fully developed and tested, you can use the npx bp login, then npx bp deploy and finally reset the Self hosted integration's url in the settings section of your integration. This will allow the integration to run on Botpress infrastructure. Once deployed you will be able to see logs in you workspace in Botpress Cloud, under the integration, then the logs tab.

   The bp login command also asks you to select a workspace to deploy the integration to. Go to your workspaces and fetch the workspace_id you'd like to deploy to.

Adding the integration to your bot

1. After which, open your workspace and click "Your Integrations".
2. Find your integration and click "Install". Select the bot from your list of bots.
3. Once the integration is installed "Configure Integration"
4. Click the "Enable integration" toggle on the top right, then hit "Save" to enable the integration.

In the bot's integration page, you will be able to add configuration variables at a later point.

Seeing your integration logs

To see the logs of your integration,

1. Open your workspace and click "Your Integrations".
2. Find your integration and click "Logs" to see the logs of your integration.

Adding Capabilities

Now that you have your integration running and installed on your bot, you can start adding capabilities to it.

• Adding Messaging Channel Capabilities
• Adding Actions & Triggers to Botpress Studio