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 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
Unique identifier for the interface. Semantic version of the interface. Human-readable title for the interface.title: 'Human-in-the-Loop Interface'
Brief description of what the interface provides.
Path to icon file (SVG recommended). Path to readme/documentation file.
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.
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
}
}
}
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.
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()
})
}
}
}
}
Custom metadata attributes.attributes: {
category: 'AI',
platform: 'Cloud'
}
Advanced configuration options.__advanced: {
useLegacyZuiTransformer: true
}
Type Definitions
GenericEventDefinition
type GenericEventDefinition<TEntities, TEvent> = {
schema: GenericZuiSchema<EntityReferences<TEntities>, TEvent>
attributes?: Record<string, string>
}
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>
}
GenericChannelDefinition
type GenericChannelDefinition<TEntities, TChannel> = {
messages: {
[K in keyof TChannel]: {
schema: GenericZuiSchema<EntityReferences<TEntities>, TChannel[K]>
}
}
}
Properties
Entity definitions defined by the interface.
Event definitions with resolved entity references.
Action definitions with resolved entity references.
Channel definitions with resolved entity references.
Interface metadata including SDK version. 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
})
}
}
}
})
z.ref() internally, allowing integrations to map them to concrete entity types.
Complete Example: HITL Interface
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
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
