- Manual configuration: Users bring their own app and manually provide Botpress with the required credentials
- OAuth: A one-click approach where users authorize the integration to access their information. This is the case for Slack, GitHub, Linear, Notion and many more.
Setup
1
Create an Application in the external service
On the platform you’re integrating with, create an OAuth application. This step varies per platform (Slack, GitHub, etc.), so refer to their documentation.When asked for an OAuth redirect URI, use:If asked for a webhook URI, use:
2
Add a link template script in your integration definition
In your integration definition, add a Your script should generate a URL similar to the one above, but adapted to the platform you’re integrating with. The important parts are:
configurations
type with a linkTemplateScript
field. This field is a path to a .vrl
script relative to your integration’s directory. The script generates the OAuth URL that users will be redirected to when clicking the OAuth button in the integration UI.For Slack, the link looks something like this:VRL - Vector Remap Language is a small domain specific language that Botpress uses to manipulate data. In this case, it allows you to dynamically generate the OAuth URL based on the integration’s configuration and the webhook ID. Your VRL script is called with the following variables:
-
The
state
parameter must equal the webhook ID and cannot contain any other information. It’s used by Botpress to identify which bot and which integration initiated the flow. -
The
redirect_uri
must be:
3
Handle the `/oauth` path in your integration
In your integration implementation, handle incoming requests with the
/oauth
path.Your code should:- Extract the access token and any other relevant data from the request
- Store the token in an integration’s state
- Call configureIntegration to associate the integration with a user or workspace ID from the third-party platform
4
Add an `identifier` with an `extractScript`
In your integration definition, add an This script is used when receiving incoming requests on the global webhook. It should extract an external user or workspace ID from the request. Botpress uses this ID to route the request to the correct bot.
identifier
field with an extractScript
:Just like the
linkTemplateScript
, this is a path to a .vrl
script relative to your integration’s directory. The script is executed when Botpress receives incoming requests on the global webhook. It should extract an external user or workspace ID from the request and return it in the format expected by Botpress. It’s called with the following variables:Use global secrets
If your OAuth flow requires credentials likeclient_id
or client_secret
, you can provide them using global secrets. These can be accessed from your VRL scripts or code.
Once all of this is set up, users installing your integration will be able to authenticate with a single click—just like they can with Slack, GitHub, and other official integrations.