# Messages & Events

Understanding how to send messages and events is critical for building conversational AI agents. This guide covers all message types, when to use them, and common pitfalls.

## Table of Contents

**Quick Links:**

- [Core Concepts](#core-concepts) - Messages vs Events, Agnostic vs Channel-Specific
- [Sending Messages in Conversations](#sending-messages-in-conversations) - Using `conversation.send()`
- [Message Metadata](#message-metadata-chat-integration) - Adding custom data to messages
- [All Message Types](#all-message-types) - Complete reference (text, image, file, card, etc.)
  - [File Messages & Metadata](#file-message-metadata) - File-specific metadata usage
  - [Custom Component (Webchat)](#custom-component-webchat) - Webchat-only custom UI components
- [Accessing Messages on Frontend](#accessing-messages-on-the-frontend) - Webchat SDK integration
- [Sending from Workflows](#sending-messages-from-workflows) - Using `client.createMessage()`
- [Sending Events (Ephemeral)](#sending-events-ephemeral) - Non-persistent notifications
- [Channel Compatibility](#channel-compatibility) - What works where
- [Common Mistakes](#common-mistakes) - Pitfalls to avoid
- [Best Practices](#best-practices) - Recommended patterns

## Core Concepts

### Messages vs Events

**Messages** are persistent conversation history items that users can see:

- Appear in chat history
- Survive page reloads
- Part of conversation context
- Sent using `conversation.send()` in conversations

**Events** are ephemeral signals that don't persist:

- NOT in conversation history
- Lost on page reload
- Used for real-time notifications
- Sent using integration actions (e.g., `bp.webchat.actions.customEvent()`)

### Agnostic vs Channel-Specific

**Agnostic Messages** work across multiple channels (defined in `@botpress/sdk`):

- `text`, `image`, `audio`, `video`, `file`, `location`
- `card`, `carousel`, `choice`, `dropdown`, `bloc`, `markdown`

**Channel-Specific Messages** only work in specific integrations:

- `customComponent` (webchat only)
- Platform-specific fields (e.g., Slack threads)

## Sending Messages in Conversations

### Basic Syntax

In conversation handlers, use `conversation.send()`:

```typescript
import { Conversation } from '@botpress/runtime'

export const Chat = new Conversation({
  channel: 'chat.channel',

  async handler({ message, conversation }) {
    // Send a message
    await conversation.send({
      type: 'text',
      payload: { text: 'Hello!' },
    })
  },
})
```

**CRITICAL**: Never use `client.createMessage()` directly in conversations. Always use `conversation.send()`.

```typescript
// ❌ WRONG - Don't use client directly
await client.createMessage({
  conversationId: conversation.id,
  type: 'text',
  payload: { text: 'Hello' },
})

// ✅ CORRECT - Use conversation.send()
await conversation.send({
  type: 'text',
  payload: { text: 'Hello' },
})
```

### Why Use `conversation.send()`?

- Automatically handles conversation context
- Type-safe for the channel
- Manages message tracking
- Integrates with ADK runtime

## Message Metadata (Chat Integration)

The **chat** integration supports an optional `metadata` field on **all message types**. This allows you to attach arbitrary custom data that will be available to the frontend.

```typescript
await conversation.send({
  type: 'text',
  payload: {
    text: 'Your order has been confirmed',
    metadata: {
      orderId: 'order_123',
      customerId: 'cust_456',
      trackingNumber: 'TRACK789',
      internalRef: 'ref_abc',
      // Any custom data you need
    },
  },
})
```

**Metadata Schema**:

- Type: `Record<string, any>` (key-value pairs)
- Keys: strings
- Values: any type (string, number, boolean, object, array)
- Optional on all message types

**Use Cases**:

- File identifiers for tracking
- Unique keys for deduplication
- Custom display properties
- Analytics tracking data
- Frontend state management

**Channel Support**:

- ✅ **chat**: Full metadata support on all message types
- ❓ **webchat**: Check generated types after adding dependency
- ❓ **Other channels**: Varies by integration

## All Message Types

### Text

Basic text message - works everywhere.

```typescript
await conversation.send({
  type: 'text',
  payload: {
    text: 'Hello, world!',
  },
})
```

### Markdown

Formatted text with markdown - **channel support varies**.

```typescript
await conversation.send({
  type: 'markdown',
  payload: {
    markdown: '**Bold** _italic_ `code` [link](https://example.com)',
  },
})
```

**Note**: Markdown support depends on the channel. Use `text` for guaranteed cross-channel compatibility.

### Image

Display an image from a URL.

```typescript
await conversation.send({
  type: 'image',
  payload: {
    imageUrl: 'https://example.com/image.png',
  },
})
```

### Audio

Play an audio file.

```typescript
await conversation.send({
  type: 'audio',
  payload: {
    audioUrl: 'https://example.com/audio.mp3',
  },
})
```

### Video

Display a video player.

```typescript
await conversation.send({
  type: 'video',
  payload: {
    videoUrl: 'https://example.com/video.mp4',
  },
})
```

### File

Share a downloadable file with optional metadata.

```typescript
await conversation.send({
  type: 'file',
  payload: {
    fileUrl: 'https://example.com/document.pdf',
    title: 'Invoice', // optional
    metadata: {
      // optional - see Message Metadata section
      fileId: 'file_123',
      uniqueKey: 'invoice-2024-001',
    },
  },
})
```

### Location

Share a geographic location.

```typescript
await conversation.send({
  type: 'location',
  payload: {
    latitude: 40.7128,
    longitude: -74.006,
    address: 'New York, NY', // optional
    title: 'Meeting Location', // optional
  },
})
```

### Card

Rich card with image, title, and action buttons.

```typescript
await conversation.send({
  type: 'card',
  payload: {
    title: 'Product Name',
    subtitle: 'Product description', // optional
    imageUrl: 'https://example.com/product.jpg', // optional
    actions: [
      {
        action: 'postback', // or "url" or "say"
        label: 'Buy Now',
        value: 'buy_product_123',
      },
      {
        action: 'url',
        label: 'Learn More',
        value: 'https://example.com/product',
      },
    ],
  },
})
```

**Action Types**:

- `postback`: Sends a value back to the bot (triggers new message)
- `url`: Opens a URL in browser
- `say`: Makes user "say" text (sends as user message)

### Carousel

Multiple cards in a scrollable carousel.

```typescript
await conversation.send({
  type: 'carousel',
  payload: {
    items: [
      {
        title: 'Product 1',
        subtitle: 'Description 1',
        imageUrl: 'https://example.com/product1.jpg',
        actions: [{ action: 'postback', label: 'Select', value: 'product_1' }],
      },
      {
        title: 'Product 2',
        subtitle: 'Description 2',
        imageUrl: 'https://example.com/product2.jpg',
        actions: [{ action: 'postback', label: 'Select', value: 'product_2' }],
      },
    ],
  },
})
```

### Choice (Buttons)

Quick reply buttons for user selection.

```typescript
await conversation.send({
  type: 'choice',
  payload: {
    text: 'What would you like to do?',
    options: [
      { label: 'Option 1', value: 'opt1' },
      { label: 'Option 2', value: 'opt2' },
      { label: 'Option 3', value: 'opt3' },
    ],
    disableFreeText: false, // optional - prevent typing
  },
})
```

### Dropdown

Dropdown/select menu for user selection.

```typescript
await conversation.send({
  type: 'dropdown',
  payload: {
    text: 'Select your country:',
    options: [
      { label: 'United States', value: 'us' },
      { label: 'Canada', value: 'ca' },
      { label: 'United Kingdom', value: 'uk' },
    ],
    disableFreeText: true, // optional
  },
})
```

### Bloc

Multiple messages grouped together (composite message).

```typescript
await conversation.send({
  type: 'bloc',
  payload: {
    items: [
      {
        type: 'text',
        payload: { text: "Here's your order summary:" },
      },
      {
        type: 'image',
        payload: { imageUrl: 'https://example.com/product.jpg' },
      },
      {
        type: 'text',
        payload: { text: 'Total: $99.99' },
      },
    ],
  },
})
```

**Allowed item types in bloc**:

- `text`, `markdown`, `image`, `audio`, `video`, `file`, `location`

### Custom Component (Webchat)

Send a custom React component in webchat conversations using the `customComponent` message type:

```typescript
import { WelcomeBannerComponent } from '../components'

await conversation.send({
  type: 'customComponent',
  payload: {
    component: WelcomeBannerComponent,
    props: {},
  },
})
```

Components are `.bp.tsx` files registered in `src/components/index.ts` with `new CustomComponent()`. See the component registry reference for the full creation flow.

When components are listed in a `Conversation`'s `components` array, the LLM can also yield them autonomously during `execute()` — no explicit `send()` needed.

**Note**: Custom components only work in webchat channels. For other channels, use agnostic message types like `card` or `carousel`.

## Accessing Messages on the Frontend

Messages (including metadata) are available to frontend clients via the webchat SDK.

### Listening to New Messages

```javascript
// React to new messages as they arrive
window.botpressWebChat.onMessage((message) => {
  console.log('New message:', message)

  if (message.type === 'file') {
    console.log('File URL:', message.payload.fileUrl)
    console.log('File title:', message.payload.title)
    console.log('Metadata:', message.payload.metadata)

    // Access custom metadata
    const { fileId, uniqueKey, customData } = message.payload.metadata || {}

    // Fetch file contents if needed
    fetch(message.payload.fileUrl)
      .then((response) => response.text())
      .then((content) => {
        console.log('File content:', content)
      })
  }
})
```

### Reconstructing State from Message History

On page reload, iterate through conversation history to reconstruct application state:

```javascript
// Get all messages from conversation history
window.botpressWebChat.getMessages().then((messages) => {
  // Filter for file messages with specific metadata
  const componentFiles = messages.filter((msg) => msg.type === 'file' && msg.payload.metadata?.fileType === 'component')

  // Reconstruct state from persisted messages
  componentFiles.forEach(async (msg) => {
    const { fileUrl, metadata } = msg.payload
    const { componentId, stepId } = metadata

    // Fetch and restore component
    const content = await fetch(fileUrl).then((r) => r.text())
    restoreComponent(componentId, stepId, content)
  })
})
```

### Message Persistence Benefits

Messages (unlike events) are:

- ✅ Persisted in conversation history
- ✅ Replayed on page reload
- ✅ Available via `getMessages()` API
- ✅ Include all metadata

This makes messages ideal for:

- State reconstruction after page reload
- File tracking and retrieval
- Workflow progress indicators
- Audit trails

## Sending Messages from Workflows

Workflows can't use `conversation.send()` - they must use `client.createMessage()`:

```typescript
import { Workflow } from '@botpress/runtime'

export const NotifyWorkflow = new Workflow({
  name: 'notify',
  input: z.object({
    conversationId: z.string(), // REQUIRED for messaging!
    message: z.string(),
  }),

  handler: async ({ input, client, step }) => {
    await step('send-notification', async () => {
      await client.createMessage({
        conversationId: input.conversationId,
        type: 'text',
        payload: { text: input.message },
      })
    })
  },
})
```

**CRITICAL**: Always pass `conversationId` to workflows that need to send messages (see Common Mistakes section for details).

## Sending Events (Ephemeral)

Events are **NOT messages** - they don't persist in conversation history. Use integration actions to send ephemeral events (see [Integration Actions for Messages](#integration-actions-for-messages) section for examples).

### When to Use Events vs Messages

**Use Messages** (persistent) when:

- User needs to see it in history
- It's part of the conversation flow
- You want it to survive page reloads
- Examples: chat responses, confirmations, results

**Use Events** (ephemeral) when:

- Real-time notifications (typing indicators, progress)
- UI state changes (show/hide widget, config updates)
- Temporary feedback (loading, processing)
- Examples: "Agent is typing...", "File uploading..."

## Integration Actions for Messages

Some integrations provide actions for special message types and events:

```typescript
// Webchat - Send custom event (ephemeral, not persisted)
await client.callAction({
  type: 'webchat:customEvent',
  input: {
    conversationId: conversation.id,
    event: JSON.stringify({
      type: 'notification',
      message: 'Processing...',
    }),
  },
})

// Webchat - Show/hide widget
await client.callAction({
  type: 'webchat:showWebchat',
  input: { conversationId: conversation.id },
})

await client.callAction({
  type: 'webchat:hideWebchat',
  input: { conversationId: conversation.id },
})

// Webchat - Update configuration
await client.callAction({
  type: 'webchat:configWebchat',
  input: {
    conversationId: conversation.id,
    config: JSON.stringify({
      theme: { primaryColor: '#ff0000' },
    }),
  },
})
```

**Frontend event handling**:

```javascript
window.botpressWebChat.onEvent(
  (event) => {
    if (event.type === 'notification') {
      showToast(event.message)
    }
  },
  ['TRIGGER']
)
```

## Channel Compatibility

Not all message types work in all channels:

| Message Type    | Chat | Webchat           | Slack | WhatsApp | Teams |
| --------------- | ---- | ----------------- | ----- | -------- | ----- |
| text            | ✅   | ✅                | ✅    | ✅       | ✅    |
| markdown        | ✅   | ✅                | ✅    | ❌       | ✅    |
| image           | ✅   | ✅                | ✅    | ✅       | ✅    |
| audio           | ✅   | ✅                | ❌    | ✅       | ❌    |
| video           | ✅   | ✅                | ❌    | ✅       | ❌    |
| file            | ✅   | ✅                | ✅    | ✅       | ✅    |
| location        | ✅   | ✅                | ❌    | ✅       | ❌    |
| card            | ✅   | ✅                | ✅    | ❌       | ✅    |
| carousel        | ✅   | ✅                | ❌    | ❌       | ❌    |
| choice          | ✅   | ✅                | ✅    | ✅       | ✅    |
| dropdown        | ✅   | ✅                | ❌    | ✅       | ❌    |
| bloc            | ✅   | ✅                | ❌    | ❌       | ❌    |
| customComponent | ❌   | ✅ (webchat only) | ❌    | ❌       | ❌    |

**Tip**: Use `text` and `image` for maximum compatibility across channels.

## Common Mistakes

### 1. Using client.createMessage() in Conversations

```typescript
// ❌ WRONG
export const Chat = new Conversation({
  async handler({ client }) {
    await client.createMessage({
      /* ... */
    })
  },
})

// ✅ CORRECT
export const Chat = new Conversation({
  async handler({ conversation }) {
    await conversation.send({
      /* ... */
    })
  },
})
```

### 2. Using client.createEvent() for Messages

```typescript
// ❌ WRONG - Events don't persist!
await client.createEvent({
  conversationId: conversation.id,
  type: 'text',
  payload: { text: 'Hello' },
})

// ✅ CORRECT - Use messages
await conversation.send({
  type: 'text',
  payload: { text: 'Hello' },
})
```

### 3. Missing conversationId in Workflows

```typescript
// ❌ WRONG - Can't send messages without conversationId
export const MyWorkflow = new Workflow({
  handler: async ({ input, client }) => {
    await client.createMessage({
      // Where's conversationId? This will fail!
      type: 'text',
      payload: { text: 'Hello' },
    })
  },
})

// ✅ CORRECT - Pass conversationId in input
export const MyWorkflow = new Workflow({
  input: z.object({
    conversationId: z.string(),
  }),
  handler: async ({ input, client }) => {
    await client.createMessage({
      conversationId: input.conversationId,
      type: 'text',
      payload: { text: 'Hello' },
    })
  },
})
```

### 4. Using Custom Components in Non-Webchat Channels

```typescript
// ❌ WRONG - customComponent only works in webchat
export const SlackChat = new Conversation({
  channel: 'slack.dm',
  async handler({ conversation }) {
    await conversation.send({
      type: 'customComponent', // Will fail in Slack!
      payload: {
        component: TicketCardComponent,
        props: {
          /* ... */
        },
      },
    })
  },
})

// ✅ CORRECT - Use agnostic message types for non-webchat channels
export const SlackChat = new Conversation({
  channel: 'slack.dm',
  async handler({ conversation }) {
    await conversation.send({
      type: 'card', // Works in Slack
      payload: { title: 'Ticket', subtitle: 'Details here', actions: [] },
    })
  },
})
```

## Best Practices

### 1. Type Safety

TypeScript will help you with type-safe payloads:

```typescript
// TypeScript knows the payload structure based on type
await conversation.send({
  type: 'card',
  payload: {
    title: 'Required',
    subtitle: 'Optional',
    // IntelliSense will suggest all valid fields!
  },
})
```

### 2. Graceful Degradation

When supporting multiple channels:

```typescript
import { TicketCardComponent } from '../components'

export const Chat = new Conversation({
  async handler({ conversation }) {
    if (conversation.channel === 'webchat.channel') {
      // Webchat supports custom components
      await conversation.send({
        type: 'customComponent',
        payload: {
          component: TicketCardComponent,
          props: { ticketId: 'TKT-001', title: 'VPN issue', priority: 'high', status: 'open' },
        },
      })
    } else {
      // Fall back to card for other channels
      await conversation.send({
        type: 'card',
        payload: {
          title: 'TKT-001: VPN issue',
          subtitle: 'Priority: high · Status: open',
          actions: [],
        },
      })
    }
  },
})
```

### 3. Error Handling

Always wrap message sending in try-catch:

```typescript
try {
  await conversation.send({
    type: 'image',
    payload: { imageUrl: maybeInvalidUrl },
  })
} catch (error) {
  console.error('Failed to send image:', error)
  // Fall back to text
  await conversation.send({
    type: 'text',
    payload: { text: 'Image unavailable' },
  })
}
```

### 4. Message Composition

Break complex messages into parts:

```typescript
// Instead of one giant text
await conversation.send({
  type: 'text',
  payload: { text: 'Title\n\nBody text here\n\nFooter' },
})

// Use bloc for better structure
await conversation.send({
  type: 'bloc',
  payload: {
    items: [
      { type: 'markdown', payload: { markdown: '**Title**' } },
      { type: 'text', payload: { text: 'Body text here' } },
      { type: 'text', payload: { text: 'Footer' } },
    ],
  },
})
```

## Summary

**In Conversations**: Use `conversation.send()` for messages (persistent, type-safe)

**In Workflows**: Use `client.createMessage()` with `conversationId` in input

**Events**: Use integration actions for ephemeral notifications (don't persist)

**Key Rules**:

1. ✅ Use `conversation.send()` in conversations, `client.createMessage()` in workflows
2. ✅ Always pass `conversationId` to workflows that send messages
3. ✅ Use messages for persistent content, events for ephemeral notifications
4. ✅ In webchat conversations, use `customComponent` message type with a `CustomComponent` reference
5. ❌ Never use `client.createMessage()` in conversations
6. ❌ Check channel compatibility for message types (see table above)