PluginDefinition

Define reusable plugin components for bots

The PluginDefinition class defines a reusable plugin that can be added to multiple bots. Plugins can provide states, events, actions, and handlers that extend bot functionality.

Constructor

import { PluginDefinition } from '@botpress/sdk'

const plugin = new PluginDefinition(props: PluginDefinitionProps)

PluginDefinitionProps

name · string · required

Unique plugin identifier.

name: 'analytics-plugin'

version · string · required

Semantic version.

version: '1.0.0'

title · string

Human-readable title.

description · string

Plugin description.

icon · string

Path to icon file.

interfaces · object

Interface dependencies required by the plugin.

interfaces: {
  storage: storageInterface
}

integrations · object

Integration dependencies.

integrations: {
  analytics: mixpanelIntegration
}

configuration · object

Plugin configuration schema.

configuration: {
  schema: z.object({
    enabled: z.boolean(),
    trackingId: z.string().optional()
  })
}

states · object

State definitions.

states: {
  sessionData: {
    type: 'user',
    schema: z.object({
      sessionId: z.string(),
      startTime: z.string().datetime()
    })
  }
}

events · object

Custom event definitions.

events: {
  eventTracked: {
    schema: z.object({
      eventName: z.string(),
      properties: z.record(z.unknown())
    })
  }
}

actions · object

Action definitions the plugin provides.

actions: {
  trackEvent: {
    title: 'Track Event',
    input: {
      schema: z.object({
        event: z.string(),
        userId: z.string(),
        properties: z.record(z.unknown()).optional()
      })
    },
    output: {
      schema: z.object({
        tracked: z.boolean()
      })
    }
  }
}

user · UserDefinition

User-level tags.

conversation · ConversationDefinition

Conversation-level tags.

message · MessageDefinition

Message-level tags.

Entity References

Plugins can reference interface entities:

import { PluginDefinition } from '@botpress/sdk'
import storageInterface from '@botpress/interface-storage'

export default new PluginDefinition({
  name: 'file-manager',
  version: '1.0.0',
  
  interfaces: {
    storage: storageInterface
  },
  
  states: {
    fileCache: {
      type: 'bot',
      schema: ({ entities }) => z.object({
        files: z.array(entities.storage.file)
      })
    }
  },
  
  actions: {
    storeFile: {
      input: {
        schema: ({ entities }) => z.object({
          file: entities.storage.file,
          metadata: z.record(z.string())
        })
      },
      output: {
        schema: z.object({
          success: z.boolean()
        })
      }
    }
  }
})

Complete Example

plugin.definition.ts

import { PluginDefinition, z } from '@botpress/sdk'
import analyticsInterface from '@botpress/interface-analytics'

export default new PluginDefinition({
  name: 'analytics-plugin',
  version: '1.0.0',
  title: 'Analytics Plugin',
  description: 'Track user interactions and events',
  icon: 'icon.svg',
  
  // Dependencies
  interfaces: {
    analytics: analyticsInterface
  },
  
  // Configuration
  configuration: {
    schema: z.object({
      enabled: z.boolean().default(true),
      sampleRate: z.number().min(0).max(1).default(1),
      excludeEvents: z.array(z.string()).optional()
    })
  },
  
  // States
  states: {
    userSession: {
      type: 'user',
      schema: z.object({
        sessionId: z.string(),
        startTime: z.string().datetime(),
        eventCount: z.number().default(0)
      })
    },
    analytics: {
      type: 'bot',
      schema: z.object({
        totalEvents: z.number(),
        lastReset: z.string().datetime()
      })
    }
  },
  
  // Events
  events: {
    eventTracked: {
      schema: z.object({
        eventName: z.string(),
        userId: z.string(),
        properties: z.record(z.unknown()),
        timestamp: z.string().datetime()
      })
    }
  },
  
  // Actions
  actions: {
    trackEvent: {
      title: 'Track Event',
      description: 'Track a custom event',
      input: {
        schema: z.object({
          event: z.string(),
          userId: z.string(),
          properties: z.record(z.unknown()).optional()
        })
      },
      output: {
        schema: z.object({
          tracked: z.boolean(),
          eventId: z.string().optional()
        })
      }
    },
    getStats: {
      title: 'Get Statistics',
      input: {
        schema: z.object({
          userId: z.string().optional()
        })
      },
      output: {
        schema: z.object({
          totalEvents: z.number(),
          period: z.string()
        })
      }
    }
  },
  
  // User tags
  user: {
    tags: {
      analyticsId: { title: 'Analytics ID' },
      segment: { title: 'User Segment' }
    }
  },
  
  // Message tags
  message: {
    tags: {
      tracked: { title: 'Tracked' }
    }
  }
})

Methods

dereferenceEntities

Resolve interface entity references.

dereferenceEntities(options?: {
  intersectWithUnknownRecord?: boolean
}): this

See Also

• PluginImplementation - Implement plugin handlers
• BotDefinition - Add plugins to bots