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 messages namespace provides ready-to-use message schema definitions for common message types used in channels. These schemas are built with ZUI and can be used directly or extended in channel definitions.
Import
import { messages } from '@botpress/sdk'
Default Message Types
The messages.defaults object contains standard message schemas for common message types.
Text Message
Schema for text messages.z.object({
text: z.string().min(1)
})
channels: {
channel: {
messages: {
text: messages.defaults.text
}
}
}
Image Message
Schema for image messages.z.object({
imageUrl: z.string().min(1),
title: z.string().min(1).optional()
})
channels: {
channel: {
messages: {
image: messages.defaults.image
}
}
}
Audio Message
Schema for audio messages.z.object({
audioUrl: z.string().min(1),
title: z.string().min(1).optional()
})
Video Message
Schema for video messages.z.object({
videoUrl: z.string().min(1),
title: z.string().min(1).optional()
})
File Message
Schema for file attachments.z.object({
fileUrl: z.string().min(1),
title: z.string().min(1).optional()
})
Location Message
messages.defaults.location
Schema for location/map messages.z.object({
latitude: z.number(),
longitude: z.number(),
address: z.string().optional(),
title: z.string().optional()
})
Card Message
Schema for rich card messages with actions.z.object({
title: z.string().min(1),
subtitle: z.string().min(1).optional(),
imageUrl: z.string().min(1).optional(),
actions: z.array(
z.object({
action: z.enum(['postback', 'url', 'say']),
label: z.string().min(1),
value: z.string().min(1)
})
)
})
// Sending a card message
await client.createMessage({
conversationId,
userId: botUserId,
type: 'card',
payload: {
title: 'Product',
subtitle: 'Check out this amazing product',
imageUrl: 'https://example.com/product.jpg',
actions: [
{ action: 'url', label: 'View', value: 'https://example.com/product' },
{ action: 'postback', label: 'Buy', value: 'buy_product_123' }
]
}
})
Carousel Message
messages.defaults.carousel
Schema for carousel (multiple cards).z.object({
items: z.array(cardSchema)
})
Choice/Dropdown Message
messages.defaults.choice
messages.defaults.dropdown
Schema for choice/dropdown messages.z.object({
text: z.string().min(1),
options: z.array(
z.object({
label: z.string().min(1),
value: z.string().min(1)
})
)
})
// Sending a choice message
await client.createMessage({
conversationId,
userId: botUserId,
type: 'choice',
payload: {
text: 'Choose your preference:',
options: [
{ label: 'Option A', value: 'a' },
{ label: 'Option B', value: 'b' },
{ label: 'Option C', value: 'c' }
]
}
})
Bloc Message
Schema for bloc messages (multiple items in sequence).z.object({
items: z.array(
z.union([
z.object({ type: z.literal('text'), payload: textMessageSchema }),
z.object({ type: z.literal('image'), payload: imageMessageSchema }),
z.object({ type: z.literal('audio'), payload: audioMessageSchema }),
z.object({ type: z.literal('video'), payload: videoMessageSchema }),
z.object({ type: z.literal('file'), payload: fileMessageSchema }),
z.object({ type: z.literal('location'), payload: locationMessageSchema })
])
)
})
// Sending a bloc with multiple items
await client.createMessage({
conversationId,
userId: botUserId,
type: 'bloc',
payload: {
items: [
{
type: 'text',
payload: { text: 'Check out this image:' }
},
{
type: 'image',
payload: { imageUrl: 'https://example.com/image.jpg' }
},
{
type: 'text',
payload: { text: 'Pretty cool, right?' }
}
]
}
})
Deprecated Message Types
Markdown Message
messages.markdown // Deprecated
The markdown message type is deprecated. Use text instead and render markdown on the client side.
z.object({
markdown: z.string().min(1)
})
Markdown Bloc
messages.markdownBloc // Deprecated
The markdownBloc message type is deprecated. Use bloc instead.
Extending Message Schemas
You can extend the default message schemas to add custom fields:
import { IntegrationDefinition, messages, z } from '@botpress/sdk'
const integration = new IntegrationDefinition({
name: 'my-integration',
version: '1.0.0',
channels: {
channel: {
messages: {
// Use default text message
text: messages.defaults.text,
// Extend image message with custom field
image: {
schema: messages.defaults.image.schema.extend({
altText: z.string().optional()
})
},
// Custom message type
customCard: {
schema: z.object({
title: z.string(),
description: z.string(),
metadata: z.record(z.string())
})
}
}
}
}
})
Using in Interfaces
Interfaces commonly use message schemas in channel definitions:
import { InterfaceDefinition, messages, z } from '@botpress/sdk'
const hitlInterface = new InterfaceDefinition({
name: 'hitl',
version: '2.0.0',
channels: {
hitl: {
messages: {
// Add userId field to allow sending messages as different users
text: {
schema: () => messages.defaults.text.schema.extend({
userId: z.string().optional()
.describe('Send message as a specific user')
})
},
image: {
schema: () => messages.defaults.image.schema.extend({
userId: z.string().optional()
})
},
// Include other message types
audio: messages.defaults.audio,
video: messages.defaults.video,
file: messages.defaults.file
}
}
}
})
Complete Channel Example
integration.definition.ts
import { IntegrationDefinition, messages, z } from '@botpress/sdk'
export default new IntegrationDefinition({
name: 'slack',
version: '1.0.0',
channels: {
channel: {
title: 'Slack Channel',
messages: {
// Standard message types
text: messages.defaults.text,
image: messages.defaults.image,
audio: messages.defaults.audio,
video: messages.defaults.video,
file: messages.defaults.file,
// Rich message types
card: messages.defaults.card,
carousel: messages.defaults.carousel,
choice: messages.defaults.choice,
// Multi-item message
bloc: messages.defaults.bloc,
// Extended message with Slack-specific fields
slackMessage: {
schema: z.object({
text: z.string(),
threadTs: z.string().optional(),
blocks: z.array(z.any()).optional()
})
}
},
message: {
tags: {
id: { title: 'Slack Message ID' },
ts: { title: 'Slack Timestamp' }
}
},
conversation: {
tags: {
channel: { title: 'Slack Channel ID' },
workspace: { title: 'Workspace ID' }
}
}
}
}
})
Type Safety
The message schemas provide full TypeScript type safety when using the client:
import { Client } from '.botpress'
const client = new Client({ token: ctx.configuration.token })
// TypeScript knows the payload structure
await client.createMessage({
conversationId,
userId: botUserId,
type: 'text',
payload: {
text: 'Hello!' // ✓ Correct
// imageUrl: 'test' // ✗ Type error
}
})
await client.createMessage({
conversationId,
userId: botUserId,
type: 'card',
payload: {
title: 'Product',
actions: [
{
action: 'url', // ✓ Valid action type
label: 'Click',
value: 'https://example.com'
}
]
}
})
See Also
