chat/docs/api/postable-message.mdx

Unified chat abstraction for Slack, Teams, Google Chat, and Discord

---
title: PostableMessage
description: The union type accepted by thread.post() for sending messages.
type: reference
---

`PostableMessage` is the union of all message formats accepted by `thread.post()` and `sent.edit()`.

```typescript
type PostableMessage =
  | AdapterPostableMessage
  | AsyncIterable<string | StreamChunk | StreamEvent>
  | PostableObject;
```

`PostableObject` covers `Plan` (mutable task lists) and `StreamingPlan` (streams with platform-specific options) — both documented below.

## String

Raw text passed through as-is to the platform.

```typescript
await thread.post("Hello world");
```

## PostableRaw

Explicit raw text — behaves the same as a plain string.

```typescript
await thread.post({ raw: "Hello world" });
```

<TypeTable
  type={{
    raw: {
      description: 'Text passed through as-is to the platform.',
      type: 'string',
    },
    attachments: {
      description: 'Typed media attachments for adapters that support outgoing attachments.',
      type: 'Attachment[]',
    },
    files: {
      description: 'Files to upload.',
      type: 'FileUpload[]',
    },
  }}
/>

## PostableMarkdown

Markdown converted to each platform's native format.

```typescript
await thread.post({ markdown: "**Bold** and _italic_" });
```

<TypeTable
  type={{
    markdown: {
      description: 'Markdown text, converted to platform format via mdast.',
      type: 'string',
    },
    attachments: {
      description: 'Typed media attachments for adapters that support outgoing attachments.',
      type: 'Attachment[]',
    },
    files: {
      description: 'Files to upload.',
      type: 'FileUpload[]',
    },
  }}
/>

## PostableAst

mdast AST converted to each platform's native format. See [Markdown](/docs/api/markdown) for builder functions.

```typescript
import { root, paragraph, text, strong } from "chat";

await thread.post({
  ast: root([paragraph([strong([text("Hello")])])]),
});
```

<TypeTable
  type={{
    ast: {
      description: 'mdast AST root node.',
      type: 'Root',
    },
    attachments: {
      description: 'Typed media attachments for adapters that support outgoing attachments.',
      type: 'Attachment[]',
    },
    files: {
      description: 'Files to upload.',
      type: 'FileUpload[]',
    },
  }}
/>

## PostableCard

Rich card with interactive elements. See [Cards](/docs/api/cards) for components.

```typescript
import { Card, Text } from "chat";

await thread.post(Card({ title: "Hello", children: [Text("World")] }));
```

You can also pass a card with explicit fallback text:

```typescript
await thread.post({
  card: Card({ title: "Hello", children: [Text("World")] }),
  fallbackText: "Hello — World",
});
```

<TypeTable
  type={{
    card: {
      description: 'Rich card element.',
      type: 'CardElement',
    },
    fallbackText: {
      description: 'Plain text fallback for clients that cannot render cards.',
      type: 'string | undefined',
    },
    files: {
      description: 'Files to upload.',
      type: 'FileUpload[]',
    },
  }}
/>

## Plan

A `Plan` is a step-by-step task list that mutates after posting. Each `addTask` / `updateTask` / `complete` call re-renders the same message in place. See [Plan API](/docs/streaming#plan-api) for full usage.

```typescript
import { Plan } from "chat";

const plan = new Plan({ initialMessage: "Researching options..." });
await thread.post(plan);
await plan.addTask({ title: "Look up records" });
await plan.complete({ completeMessage: "Done!" });
```

Adapters that don't support `PostableObject` editing render the plan as fallback text and ignore subsequent mutations.

## StreamingPlan

Wraps an async iterable with platform-specific streaming options. Use this when you need to pass options like task grouping or stop blocks through `thread.post()`. See [Streaming with options](/docs/streaming#streaming-with-options).

```typescript
import { StreamingPlan } from "chat";

const planned = new StreamingPlan(stream, {
  groupTasks: "plan",
  endWith: [feedbackBlock],
  updateIntervalMs: 750,
});

await thread.post(planned);
```

<TypeTable
  type={{
    groupTasks: {
      description: 'Slack: render task_update chunks as `"plan"` (single grouped block) or `"timeline"` (inline cards, default).',
      type: '"plan" | "timeline" | undefined',
    },
    endWith: {
      description: 'Slack: Block Kit elements appended when the stream stops (e.g. retry / feedback buttons).',
      type: 'unknown[] | undefined',
    },
    updateIntervalMs: {
      description: 'Post+edit adapters: minimum interval between update cycles in ms.',
      type: 'number | undefined',
      default: '500',
    },
  }}
/>

## AsyncIterable (streaming)

An async iterable of strings, `StreamChunk` objects, or stream events. The SDK streams the message in real time using platform-native APIs where available.

You can yield structured `StreamChunk` objects for rich content like task progress cards on platforms that support it (Slack). See [Streaming](/docs/streaming#structured-streaming-chunks-slack-only) for details.

Both AI SDK stream types are supported:

```typescript
// fullStream (recommended) — preserves step boundaries in multi-step agents
const result = await agent.stream({ prompt: message.text });
await thread.post(result.fullStream);

// textStream — plain string chunks
await thread.post(result.textStream);
```

When using `fullStream`, the SDK auto-detects `text-delta` and `finish-step` events, extracting text and inserting paragraph breaks between agent steps.

## FileUpload

Used in the `files` field of any structured message format.

<TypeTable
  type={{
    data: {
      description: 'Binary file data.',
      type: 'Buffer | Blob | ArrayBuffer',
    },
    filename: {
      description: 'Filename.',
      type: 'string',
    },
    mimeType: {
      description: 'MIME type (inferred from filename if not provided).',
      type: 'string | undefined',
    },
  }}
/>