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, auto-generated 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 you bot developers see when installing the integration in the Studio.

Integration 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.

​
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 are 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 are 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 are not 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.