Messages

Pre-built message schema definitions for common message types

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

messages.defaults.text

schema · ZodObject

Schema for text messages.

z.object({
  text: z.string().min(1)
})

Example Usage:

channels: {
  channel: {
    messages: {
      text: messages.defaults.text
    }
  }
}

Image Message

messages.defaults.image

schema · ZodObject

Schema for image messages.

z.object({
  imageUrl: z.string().min(1),
  title: z.string().min(1).optional()
})

Example:

channels: {
  channel: {
    messages: {
      image: messages.defaults.image
    }
  }
}

Audio Message

messages.defaults.audio

schema · ZodObject

Schema for audio messages.

z.object({
  audioUrl: z.string().min(1),
  title: z.string().min(1).optional()
})

Video Message

messages.defaults.video

schema · ZodObject

Schema for video messages.

z.object({
  videoUrl: z.string().min(1),
  title: z.string().min(1).optional()
})

File Message

messages.defaults.file

schema · ZodObject

Schema for file attachments.

z.object({
  fileUrl: z.string().min(1),
  title: z.string().min(1).optional()
})

Location Message

messages.defaults.location

schema · ZodObject

Schema for location/map messages.

z.object({
  latitude: z.number(),
  longitude: z.number(),
  address: z.string().optional(),
  title: z.string().optional()
})

Card Message

messages.defaults.card

schema · ZodObject

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)
    })
  )
})

Example:

// 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 · ZodObject

Schema for carousel (multiple cards).

z.object({
  items: z.array(cardSchema)
})

Choice/Dropdown Message

messages.defaults.choice
messages.defaults.dropdown

schema · ZodObject

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)
    })
  )
})

Example:

// 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

messages.defaults.bloc

schema · ZodObject

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 })
    ])
  )
})

Example:

// 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.

schema · ZodObject

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

• ZUI - Schema system used for message definitions
• IntegrationDefinition - Define channels with messages
• InterfaceDefinition - Use messages in interface definitions
• ChannelDefinition - Channel configuration reference