Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/botpress/botpress/llms.txt

Use this file to discover all available pages before exploring further.

The BotDefinition class defines the structure and capabilities of a Botpress bot. It specifies states, events, actions, integrations, and other bot-level configuration.

​
Constructor

import { BotDefinition } from '@botpress/sdk'

const bot = new BotDefinition(props: BotDefinitionProps)

​
BotDefinitionProps

​
states
object
State definitions for the bot. States can be scoped to bot, user, conversation, or workflow.
states: {
  userProfile: {
    type: 'user',
    schema: z.object({
      name: z.string(),
      email: z.string().email()
    }),
    expiry: 86400 // seconds
  },
  conversationContext: {
    type: 'conversation',
    schema: z.object({
      topic: z.string(),
      startedAt: z.string().datetime()
    })
  },
  botConfig: {
    type: 'bot',
    schema: z.object({
      version: z.string()
    })
  }
}
​
events
object
Custom event definitions for the bot.
events: {
  orderPlaced: {
    schema: z.object({
      orderId: z.string(),
      amount: z.number(),
      items: z.array(z.string())
    }),
    attributes: {
      category: 'commerce'
    }
  }
}
​
recurringEvents
object
Scheduled events that trigger on a cron schedule.
recurringEvents: {
  dailyReport: {
    type: 'reportGenerated',
    payload: z.object({}),
    schedule: {
      cron: '0 9 * * *' // 9 AM daily
    }
  }
}
​
actions
object
Action definitions that can be called by the bot.
actions: {
  processPayment: {
    title: 'Process Payment',
    description: 'Process a customer payment',
    input: {
      schema: z.object({
        amount: z.number(),
        currency: z.string()
      })
    },
    output: {
      schema: z.object({
        transactionId: z.string(),
        status: z.enum(['success', 'failed'])
      })
    },
    attributes: {
      category: 'payment'
    }
  }
}
​
tables
object
Table definitions for structured data storage.
tables: {
  orders: {
    schema: z.object({
      userId: z.string(),
      productId: z.string(),
      quantity: z.number(),
      status: z.enum(['pending', 'completed'])
    }),
    indexes: ['userId', 'status']
  }
}
​
workflows
object
EXPERIMENTAL - Workflow definitions for multi-step processes.
workflows: {
  onboarding: {
    title: 'User Onboarding',
    description: 'Multi-step user onboarding process',
    input: {
      schema: z.object({
        userId: z.string()
      })
    },
    output: {
      schema: z.object({
        completed: z.boolean()
      })
    },
    tags: {
      priority: { title: 'Priority' },
      assignee: { title: 'Assignee' }
    }
  }
}
​
user
object
User-level configuration and tags.
user: {
  tags: {
    vip: { 
      title: 'VIP Status',
      description: 'Premium customer' 
    },
    segment: { title: 'Customer Segment' }
  }
}
​
conversation
object
Conversation-level configuration and tags.
conversation: {
  tags: {
    priority: { title: 'Priority' },
    department: { title: 'Department' }
  }
}
​
message
object
Message-level configuration and tags.
message: {
  tags: {
    sentiment: { title: 'Sentiment' },
    category: { title: 'Category' }
  }
}
​
configuration
object
Bot configuration schema.
configuration: {
  schema: z.object({
    apiKey: z.string(),
    webhookUrl: z.string().url()
  })
}
​
integrations
object
Integration instances (added via addIntegration()).
​
plugins
object
Plugin instances (added via addPlugin()).
​
attributes
object
Custom metadata attributes.
attributes: {
  category: 'customer-service',
  version: '2.0',
  author: 'team@company.com'
}

​
Methods

​
addIntegration

Add an integration to the bot. 
addIntegration<I extends IntegrationPackage>(
  integrationPkg: I, 
  config?: IntegrationConfigInstance<I>
): this
Parameters:
​
integrationPkg
IntegrationPackage
required
The integration package to add.
​
config
object
Integration configuration.
​
alias
string
Unique alias for this integration instance. Defaults to integration name.
​
enabled
boolean
Whether the integration is enabled.
​
configuration
object
Integration-specific configuration values.
​
configurationType
string
For integrations with multiple configurations, specify which to use.
​
disabledChannels
string[]
List of channel names to disable.
Example: 
import github from './integrations/github'
import slack from './integrations/slack'

const bot = new BotDefinition({})
  .addIntegration(github, {
    alias: 'github',
    enabled: true,
    configurationType: 'oauth',
    configuration: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET
    }
  })
  .addIntegration(slack, {
    configuration: {
      botToken: process.env.SLACK_BOT_TOKEN
    }
  })

​
addPlugin

Add a plugin to the bot. 
addPlugin<P extends PluginPackage>(
  pluginPkg: P,
  config: PluginConfigInstance<P>
): this
Parameters:
​
pluginPkg
PluginPackage
required
The plugin package to add.
​
config
object
required
Plugin configuration.
​
alias
string
Unique alias for the plugin. Defaults to plugin name.
​
configuration
object
Plugin-specific configuration.
​
dependencies
object
required
Map plugin dependencies to bot integrations.
dependencies: {
  // For interface dependencies
  storage: {
    integrationAlias: 's3',
    integrationInterfaceAlias: 'fileStorage'
  },
  // For integration dependencies
  messaging: {
    integrationAlias: 'slack'
  }
}
Example: 
import analyticsPlugin from './plugins/analytics'
import mixpanel from './integrations/mixpanel'

const bot = new BotDefinition({})
  .addIntegration(mixpanel, { alias: 'analytics' })
  .addPlugin(analyticsPlugin, {
    alias: 'analytics',
    configuration: {
      trackingEnabled: true
    },
    dependencies: {
      analyticsProvider: {
        integrationAlias: 'analytics'
      }
    }
  })

​
dereferencePluginEntities

Resolve plugin entity references to their backing integration schemas. 
dereferencePluginEntities(): this
Returns: A copy of the bot definition with all plugin entity references resolved.

​
Properties

​
metadata
object
Bot metadata including SDK version.
{
  sdkVersion: string
}
​
withPlugins
object
Bot definition with plugin states, events, and actions merged in.

​
Type Definitions

​
StateType

type StateType = 'conversation' | 'user' | 'bot' | 'workflow'

​
StateDefinition

type StateDefinition<TState> = {
  type: StateType
  schema: TState
  expiry?: number // seconds
}

​
EventDefinition

type EventDefinition<TEvent> = {
  schema: TEvent
  attributes?: Record<string, string>
}

​
ActionDefinition

type ActionDefinition<TAction> = {
  title?: string
  description?: string
  input: { schema: TAction }
  output: { schema: ZuiObjectSchema }
  attributes?: Record<string, string>
}

​
WorkflowDefinition

type WorkflowDefinition<TWorkflow> = {
  title?: string
  description?: string
  input: { schema: TWorkflow }
  output: { schema: ZuiObjectSchema }
  tags?: Record<string, TagDefinition>
}

​
TagDefinition

type TagDefinition = {
  title?: string
  description?: string
}

​
Complete Example

bot.definition.ts
import { BotDefinition, z } from '@botpress/sdk'
import github from './integrations/github'
import slack from './integrations/slack'
import linear from './integrations/linear'

export default new BotDefinition({
  // State definitions
  states: {
    userProfile: {
      type: 'user',
      schema: z.object({
        name: z.string(),
        email: z.string().email(),
        preferences: z.array(z.string())
      })
    },
    conversationTopic: {
      type: 'conversation',
      schema: z.object({
        topic: z.string(),
        relatedIssues: z.array(z.string())
      })
    }
  },
  
  // Custom events
  events: {
    issueCreated: {
      schema: z.object({
        issueId: z.string(),
        title: z.string(),
        priority: z.enum(['low', 'medium', 'high'])
      })
    }
  },
  
  // Recurring events
  recurringEvents: {
    dailyDigest: {
      type: 'digestGenerated',
      payload: z.object({}),
      schedule: {
        cron: '0 9 * * *'
      }
    }
  },
  
  // Actions
  actions: {
    createTicket: {
      title: 'Create Support Ticket',
      input: {
        schema: z.object({
          title: z.string(),
          description: z.string(),
          priority: z.enum(['low', 'medium', 'high'])
        })
      },
      output: {
        schema: z.object({
          ticketId: z.string(),
          url: z.string().url()
        })
      }
    }
  },
  
  // User tags
  user: {
    tags: {
      tier: { title: 'Customer Tier' },
      verified: { title: 'Verified User' }
    }
  },
  
  // Conversation tags
  conversation: {
    tags: {
      priority: { title: 'Priority' },
      assignee: { title: 'Assignee' }
    }
  }
})
  .addIntegration(github, {
    enabled: true,
    configurationType: 'oauth',
    configuration: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!
    }
  })
  .addIntegration(slack, {
    configuration: {
      botToken: process.env.SLACK_BOT_TOKEN!
    }
  })
  .addIntegration(linear, {
    configuration: {
      apiKey: process.env.LINEAR_API_KEY!
    }
  })

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us