Integration definition

Define the structure and capabilities of your integration

The integration definition specifies channels, actions, events, configuration, and other properties of your integration.

Basic structure

integration.definition.ts

import { IntegrationDefinition, z } from '@botpress/sdk'

export default new IntegrationDefinition({
  name: 'workspace/integration-name',
  version: '1.0.0',
  title: 'Integration Title',
  description: 'Integration description',
  icon: 'icon.svg',
  readme: 'hub.md',
})

Required properties

Name

Integration name with workspace handle:

name: 'acme/slack'

Integration names must include your workspace handle in the format workspace/integration-name.

Version

Semantic version:

version: '1.0.0'

Optional metadata

Title and description

title: 'Slack Integration',
description: 'Connect your bot to Slack workspaces',

Icon

SVG icon file:

icon: 'icon.svg'

README

Markdown documentation:

readme: 'hub.md'

Attributes

Metadata attributes:

attributes: {
  category: 'Communication & Channels',
  featured: 'true',
}

Configuration

Define required configuration:

configuration: {
  schema: z.object({
    botToken: z.string().min(1).describe('Bot Token'),
    workspace: z.string().optional(),
  }),
}

Multiple configurations

configurations: {
  oauth: {
    schema: z.object({
      clientId: z.string(),
      clientSecret: z.string(),
    }),
  },
  apiToken: {
    schema: z.object({
      apiToken: z.string(),
    }),
  },
}

Type signature

class IntegrationDefinition<
  TName extends string,
  TVersion extends string,
  TConfig extends BaseConfig,
  TConfigs extends BaseConfigs,
  TEvents extends BaseEvents,
  TActions extends BaseActions,
  TChannels extends BaseChannels,
  TStates extends BaseStates,
  TEntities extends BaseEntities
> {
  constructor(props: IntegrationDefinitionProps)
  
  extend<P extends InterfacePackage>(
    interfacePkg: P,
    builder: ExtensionBuilder
  ): this
}