BotDefinition

Define bot structure, integrations, states, events, and actions

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: '[e-mail]'
}

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

• BotImplementation - Implement bot handlers
• BotSpecificClient - Type-safe API client
• BotHandlers - Event and message handlers