Enable OAuth

Some Botpress-maintained integrations offer bot builders the choice between two different configuration methods:

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.

This feature isn’t limited to official Botpress integrations—you can also enable OAuth in your own integrations. This guide walks you through how to do that.

Setup

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:

https://webhook.botpress.cloud/oauth

If asked for a webhook URI, use:

https://webhook.botpress.cloud/integration/global/$YOUR_INTEGRATION_NAME

Add a link template script in your integration definition

In your integration definition, add a 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:

https://slack.com/oauth/v2/authorize?client_id=12345.67890&state={{ webhookId }}&redirect_uri={{ webhookUrl }}/oauth

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:

type ScriptInput = {
  webhookId: string,   /** The integration's webhook ID */
  webhookUrl: string,  /** Botpress's global webhook endpoint */
}

Your script should generate a URL similar to the one above, but adapted to the platform you’re integrating with. The important parts are:

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:
```
{{ webhookUrl }}/oauth
```

When the OAuth flow completes, the platform will redirect to this URL, and Botpress will forward the request to your integration’s webhook handler.

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

Add an `identifier` with an `extractScript`

In your integration definition, add an identifier field with an extractScript:

identifier: {
  extractScript: 'extract-id.vrl'
}

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:

type ScriptInput = {
  path: string,                     /** The request path */
  method: string,                   /** The request HTTP method */
  query: string,                    /** The request query parameters */
  body?: string,                    /** The request body */
  headers: Record<string, string>,  /** The request headers */
  secrets: Record<string, string>,  /** The global secrets of your integration */
}

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.

Use global secrets

If your OAuth flow requires credentials like client_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.

What’s Next?

If you feel like this page is missing some information, refer to the Botpress GitHub repository for examples of OAuth integrations. These examples showcase how OAuth can be implemented effectively and provide inspiration for your own integrations.

We left these integrations open-source for a reason! Feel free to explore the code, copy it, and adapt it to your own needs. If you find areas for improvement, you can contribute by opening an issue or a pull request.