InterfaceDefinition

Define reusable interface contracts for entities, actions, events, and channels

The InterfaceDefinition class defines a reusable contract that integrations can implement. Interfaces allow you to standardize common patterns (like HITL, LLM, or storage capabilities) across multiple integrations.

Constructor

import { InterfaceDefinition } from '@botpress/sdk'

const interface = new InterfaceDefinition(props: InterfaceDefinitionProps)

InterfaceDefinitionProps

name · string · required

Unique identifier for the interface.

name: 'hitl'

version · string · required

Semantic version of the interface.

version: '2.0.0'

title · string

Human-readable title for the interface.

title: 'Human-in-the-Loop Interface'

description · string

Brief description of what the interface provides.

icon · string

Path to icon file (SVG recommended).

icon: 'icon.svg'

readme · string

Path to readme/documentation file.

entities · object

Entity definitions that integrations must provide schemas for.

entities: {
  hitlSession: {
    title: 'HITL Session',
    description: 'A HITL session, often referred to as a ticket',
    schema: z.object({})
  },
  modelRef: {
    schema: ModelRefSchema
  }
}

Entities in interfaces act as type parameters. Integrations that implement the interface must map these to concrete entity types.

events · object

Event definitions the interface can emit. Events can reference entities.

events: {
  hitlAssigned: {
    schema: () => z.object({
      conversationId: z.string()
        .title('HITL session ID')
        .describe('ID of the Botpress conversation'),
      userId: z.string()
        .title('Human agent user ID')
    }),
    attributes: {
      ...WELL_KNOWN_ATTRIBUTES.HIDDEN_IN_STUDIO
    }
  }
}

actions · object

Action definitions that integrations must implement.

actions: {
  generateContent: {
    billable: true,
    cacheable: true,
    input: {
      schema: ({ modelRef }) => GenerateContentInputSchema(modelRef)
    },
    output: {
      schema: () => GenerateContentOutputSchema
    }
  }
}

Actions can use entity references in their schemas. The schema property is a function that receives entity references as a parameter.

channels · object

Channel definitions for message-based communication.

channels: {
  hitl: {
    messages: {
      text: {
        schema: () => z.object({
          text: z.string(),
          userId: z.string().optional()
        })
      },
      image: {
        schema: () => z.object({
          imageUrl: z.string(),
          userId: z.string().optional()
        })
      }
    }
  }
}

attributes · object

Custom metadata attributes.

attributes: {
  category: 'AI',
  platform: 'Cloud'
}

__advanced · object

Advanced configuration options.

__advanced: {
  useLegacyZuiTransformer: true
}

Type Definitions

GenericEventDefinition

type GenericEventDefinition<TEntities, TEvent> = {
  schema: GenericZuiSchema<EntityReferences<TEntities>, TEvent>
  attributes?: Record<string, string>
}

Defines an event that can reference entities defined in the interface.

GenericActionDefinition

type GenericActionDefinition<TEntities, TAction> = {
  title?: string
  description?: string
  billable?: boolean
  cacheable?: boolean
  input: { schema: GenericZuiSchema<EntityReferences<TEntities>, TAction> }
  output: { schema: GenericZuiSchema<EntityReferences<TEntities>, ZuiObjectSchema> }
  attributes?: Record<string, string>
}

Defines an action with input/output schemas that can reference entities.

GenericChannelDefinition

type GenericChannelDefinition<TEntities, TChannel> = {
  messages: {
    [K in keyof TChannel]: {
      schema: GenericZuiSchema<EntityReferences<TEntities>, TChannel[K]>
    }
  }
}

Defines a channel with message types that can reference entities.

Properties

name · string

The interface name.

version · string

The interface version.

title · string | undefined

Human-readable title.

description · string | undefined

Interface description.

entities · object

Entity definitions defined by the interface.

events · object

Event definitions with resolved entity references.

actions · object

Action definitions with resolved entity references.

channels · object

Channel definitions with resolved entity references.

metadata · object

Interface metadata including SDK version.

{
  sdkVersion: string
}

Understanding Entity References

Interfaces use a generic system where entities act as type parameters. When you define an action or event schema, you receive entity references that can be used in your schema:

const myInterface = new InterfaceDefinition({
  name: 'example',
  version: '1.0.0',
  entities: {
    file: {
      schema: z.object({
        id: z.string(),
        name: z.string()
      })
    }
  },
  actions: {
    uploadFile: {
      input: {
        // The entities parameter contains references to defined entities
        schema: ({ file }) => z.object({
          file: file, // Reference to the file entity
          destination: z.string()
        })
      },
      output: {
        schema: ({ file }) => z.object({
          uploadedFile: file
        })
      }
    }
  }
})

The entity references are automatically transformed to use z.ref() internally, allowing integrations to map them to concrete entity types.

Complete Example: HITL Interface

interface.definition.ts

import { InterfaceDefinition, z } from '@botpress/sdk'
import * as messages from '@botpress/sdk/messages'

export default new InterfaceDefinition({
  name: 'hitl',
  version: '2.0.0',
  title: 'Human-in-the-Loop',
  description: 'Interface for human agent handoff systems',
  
  // Define entity templates
  entities: {
    hitlSession: {
      title: 'HITL session',
      description: 'A HITL session, often referred to as a ticket',
      schema: z.object({}) // Integrations will extend this
    }
  },
  
  // Events that integrations must fire
  events: {
    hitlAssigned: {
      schema: () => z.object({
        conversationId: z.string()
          .title('HITL session ID')
          .describe('ID of the Botpress conversation representing the HITL session'),
        userId: z.string()
          .title('Human agent user ID')
          .describe('ID of the Botpress user representing the human agent')
      }),
      attributes: {
        hiddenInStudio: 'true'
      }
    },
    hitlStopped: {
      schema: () => z.object({
        conversationId: z.string()
          .title('HITL session ID')
      }),
      attributes: {
        hiddenInStudio: 'true'
      }
    }
  },
  
  // Actions that integrations must implement
  actions: {
    createUser: {
      title: 'Create external user',
      description: 'Create an end user in the external service',
      input: {
        schema: () => z.object({
          name: z.string().title('Display name'),
          pictureUrl: z.string().title('Picture URL').optional(),
          email: z.string().title('Email address').optional()
        })
      },
      output: {
        schema: () => z.object({
          userId: z.string().title('Botpress user ID')
        })
      },
      attributes: {
        hiddenInStudio: 'true'
      }
    },
    startHitl: {
      title: 'Start new HITL session',
      description: 'Create a new HITL session in the external service',
      input: {
        schema: (entities) => z.object({
          userId: z.string().title('User ID'),
          title: z.string().title('Title').optional(),
          description: z.string().title('Description').optional(),
          hitlSession: entities.hitlSession
            .optional()
            .title('Extra configuration'),
          messageHistory: z.array(z.any())
            .title('Conversation history')
        })
      },
      output: {
        schema: () => z.object({
          conversationId: z.string().title('HITL session ID')
        })
      },
      attributes: {
        hiddenInStudio: 'true'
      }
    },
    stopHitl: {
      title: 'Stop HITL session',
      description: 'Stop an existing HITL session',
      input: {
        schema: () => z.object({
          conversationId: z.string().title('HITL session ID')
        })
      },
      output: {
        schema: () => z.object({})
      },
      attributes: {
        hiddenInStudio: 'true'
      }
    }
  },
  
  // Message channels
  channels: {
    hitl: {
      messages: {
        text: {
          schema: () => z.object({
            text: z.string(),
            userId: z.string().optional()
              .describe('Allows sending a message as a certain user')
          })
        },
        image: {
          schema: () => z.object({
            imageUrl: z.string(),
            userId: z.string().optional()
          })
        }
      }
    }
  }
})

Complete Example: LLM Interface

interface.definition.ts

import { InterfaceDefinition, z } from '@botpress/sdk'
import * as llmSchemas from './schemas'

export default new InterfaceDefinition({
  name: 'llm',
  version: '9.0.1',
  title: 'Large Language Model',
  description: 'Interface for LLM providers',
  
  entities: {
    modelRef: {
      schema: llmSchemas.ModelRefSchema
    }
  },
  
  actions: {
    generateContent: {
      billable: true,
      cacheable: true,
      input: {
        schema: ({ modelRef }) => 
          llmSchemas.GenerateContentInputSchema(modelRef)
      },
      output: {
        schema: () => llmSchemas.GenerateContentOutputSchema
      }
    },
    listLanguageModels: {
      input: {
        schema: () => z.object({})
      },
      output: {
        schema: ({ modelRef }) => z.object({
          models: z.array(z.intersection(
            llmSchemas.ModelSchema,
            modelRef
          ))
        })
      }
    }
  }
})

Implementing an Interface

Integrations implement interfaces using the extend method. See IntegrationDefinition for details on implementing interfaces.

When an integration extends an interface, it must:

• Map interface entities to concrete entity types
• Implement all required actions
• Fire all required events
• Support all defined channels

See Also

• IntegrationDefinition - Define and extend interfaces in integrations
• ZUI - Schema system used for entity, action, and event definitions
• EntityDefinition - Entity definition reference