Integrations Concepts

This guide is a breakdown of the concepts introduced in the Get Started and Messaging guides. The goal is to provide a deeper understanding of the concepts and components that make up integrations in Botpress.

Most concepts listed below can define data schemas. For this the SDK uses Zod, a TypeScript-first schema validation library. These schemas allow for better IntelliSense for integration developers, autogenerated forms for bot developers in the Studio and validation of data at runtime

Configuration

Integrations can define a configuration schema. This dictates the structure of data that bot developers must provide when installing the integration. This schema is used to display the form bot developers see when installing the integration in the Studio. For example, you can define a schema that:

• Requires users to supply their own API key (or other secrets)
• Provides additional configuration options for the integration

Example: Linear

Here’s how the official Linear integration defines its configuration schema:

export const configurations = {
  apiKey: {
    title: 'API Key',
    description: 'Configure Linear with an API Key.',
    schema: z.object({
      apiKey: z.string().title('API Key').describe('The API key for Linear'),
      webhookSigningSecret: z
        .string()
        .secret()
        .title('Webhook Signing Secret')
        .describe('The secret key for verifying incoming Linear webhook events'),
    }),
  },
} as const satisfies IntegrationDefinitionProps['configurations']

And how the configuration schema is rendered in Botpress Studio:

Provide multiple schemas

Integrations can also provide multiple configuration schemas to support different use cases or environments. This allows bot developers to select the appropriate configuration method based on their needs.

Example: GitHub

For example, here’s how the official GitHub integration defines its configuration schemas:

export const configurations = {
  manualApp: {
    title: 'Manual configuration',
    description: 'Configure manually with your own GitHub App',
    schema: z.object({
      githubAppId: z
        .string()
        .min(1)
        .title('GitHub App ID')
        .describe('Can be found in the GitHub App settings. OAuth apps are not supported.'),
      githubAppPrivateKey: multiLineString
        .min(1)
        .secret()
        .title('GitHub App Private Key')
        .describe('The raw contents of the RSA private key. Can be downloaded from the GitHub App settings.')
        .placeholder('-----BEGIN RSA PRIVATE KEY-----\n\n...\n\n-----END RSA PRIVATE KEY-----'),
      githubAppInstallationId: z
        .number()
        .positive()
        .title('GitHub App Installation ID')
        .describe('Please refer to the integration documentation for details on how to obtain this.'),
      ...webhookSecret,
    }),
  },
  manualPAT: {
    title: 'Manual configuration',
    description: 'Configure manually with a Personal Access Token',
    schema: z.object({
      personalAccessToken: z
        .string()
        .min(1)
        .secret()
        .title('Personal Access Token')
        .describe('An organization-level GitHub Personal Access Token with the necessary permissions.'),
      ...webhookSecret,
    }),
  },
} as const satisfies sdk.IntegrationDefinitionProps['configurations']

And how they’re rendered in Botpress Studio:

First schema

Events

Integrations define events that represent activities within the external service. For example:

• A Slack integration might define a memberLeftChannel event
• A GitHub integration might define a pullRequestOpened event
• A Dropbox integration might define a fileUploaded event

Events are defined with a schema that specifies the data structure of the event payload. Bots can subscribe to these events to trigger specific handlers or Workflows.

Actions

Integrations expose actions that bots can invoke to interact with the external service. For example:

• Retrieving or updating information in external systems
• Performing operations on behalf of users

Actions are defined with an input and output schema, which specifies the expected data structure for both the input parameters and the response. These actions are made available to bots in the Studio with action cards.

Channels

Integrations can define communication channels that represent different communication mediums within the integrated platform. For example:

• Different channels might represent group chats, direct messages, or threads
• Each channel specifies the types of messages it can send and receive
• Channel definitions handle platform-specific message formatting and delivery

For example, a GitHub integration might define a pullRequest channel and an issue channel, each with its own message format and delivery method.

States

Integrations can define states which are data structures attached to either a conversation, a user, or global to the whole bot. When defining a state, the integration must provide its schema, which describes the data structure of the state’s payload.

Tags

Integrations can define tags that allow bot developers to add metadata to conversations, individual messages, or users. Only tags defined in the integration definition can be used at runtime.

Just like states, tags can be used as a form of memory, enabling the integration to store and retrieve information. However, tags have key differences from states:

• Tags values must be strings of less than 500 characters. This is to ensure that tags are lightweight and easy to manage.
• Tags can be used as filters for many list and get-or-create operations like listMessages and getOrCreateUser.
• Tags are returned in the Botpress API with the entities they’re attached to. If you get a message, user or conversation, you will also get the tags attached to it without having to do a separate API call.

Secrets

Integrations can define secrets, such as API keys, tokens, or other sensitive values. While they’re most often used for authentication with external services, they can represent any sensitive information required by the integration.

Secrets are defined in the integration definition. When deploying the CLI prompts for secrets and prevents deployment if a required secret is omitted. The secret values are then available at runtime for the integration developer to use.

Secrets are global to the integration and aren’t scoped to individual bots.

What’s Next?

Now that you have a better understanding of these concepts, you should be able to build a nice and complete integration.

You can check the Publish on Botpress Hub page to learn how to publish your integration publicly and share it with the Botpress community.

You could also read the Enable OAuth page to learn how to allow users to install your integration with OAuth.