Botpress Integration Documentation

The Botpress SDK provides a structured way for developers to create new integrations for their chatbots. In this documentation, we're using the Slack integration class as a reference to illustrate the process.

Key Concepts

1. Tags

These identify users, conversations, and messages in the external system (e.g., Slack). Each tag is assigned a unique identifier.

2. Channels

Define which channels the integration supports. Channels can be group conversations, direct messages, or others, depending on the external system.

3. Configuration

This is where sensitive information, such as API keys and tokens, is stored. The configuration is used to validate the integration setup.

4. User

This refers to the mapping between the external system and Botpress. It defines how users are identified and created in the bot system.

5. Conversation

This refers to the dialogue happening between the external system, the user, and the bot. It holds the mapping between the conversation ID in the external system and the conversation ID in Botpress.

6. Messages

These are payloads exchanged between the external system, the user, and the bot within a conversation. Messages contain information essential to map interactions between the systems and hold valuable data for the conversation designer.

7. States

The state is responsible for associating data with a user, a conversation, or in a global context to store important information that needs to be tracked.

8. Actions

Actions are tasks that the integration can perform. These could be sending a message, adding a reaction, or any other function that the external system supports.

9. Events

These are non-conversational incidents that are triggered and captured by the system. For example, in Linear, an event could be when a new issue is created; in WhatsApp, it could be when someone opens the chat.

10. Definition

Everything within the integration needs to be defined before use. This is done in the IntegrationDefinition class.

11. Secrets

Finally, Botpress securely handles sensitive information like API keys or tokens in the Secrets field of the IntegrationDefinition class. This field defines and manages the secrets needed by the integration, keeping them secure from potential security breaches.