# Post to a chat

`POST /chat.post`

## Description

Post a message to a chat. Messages can be plain markdown text, rich [Block Kit](/docs/guides/block-kit) layouts, or polls.

Messages may be posted to a chat, a group, or one or more addresses (e.g. users, bots).

Mentions are supported with the syntax `<@USER_ID>`, e.g. `<!@U-7861a4c6-765a-495d-898d-fae3d8fbba2d>` or `<@all>` to notify everyone in the chat.
When rendered in the client, the tag will automatically be replaced with the human-readable display name (or "everyone" for `<@all>`).

**Access:** Organization and Personal. In Organization mode, messages are sent with the app's bot persona. In Personal mode, messages are sent as the authenticated user.

**Required scope:** `chat:send_message` or `chat:write`

---

**OpenAPI Spec:** [chat.json](https://developer.ro.am/chat.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chat` | object | Yes | A Tagged ID (chat, group, or address). You can also provide an array of user addresses to create a Multi-DM. |
| `threadTimestamp` | integer | No | Reply to a specific thread by providing the thread's timestamp. If the timestamp doesn't correspond to an existing message, a 400 error is returned. Mutually exclusive with `threadKey`.  |
| `threadKey` | string | No | A stable external identifier used to group related messages into a thread. On the first use of a given `threadKey`, a new message is posted and the resulting thread timestamp is stored. Subsequent mes |
| `text` | string | No | Markdown-formatted text content. Required unless `blocks` is provided. Cannot be combined with `blocks`.  |
| `markdown` | boolean | No | Text is markdown by default. If this is set to false, markdown interpretation will be disabled. |
| `items` | string[] | No | Array of Item IDs to attach to this message. Cannot be combined with `blocks`. |
| `blocks` | object[] | No | Array of [Block Kit](/docs/guides/block-kit) block objects for rich message formatting. Cannot be combined with `text` or `items`. Maximum 10 blocks, 8,000 bytes total payload.  |
| `color` | string | No | Colored vertical strip on the side of the message. Only used with `blocks`. Named values: `good` (green), `warning` (yellow), `danger` (red), or a hex color like `#5B3FD9`.  |
| `poll` | object | No | Create a poll message. Mutually exclusive with `text`, `items`, and `blocks`.  |
| `sync` | boolean | No | If set, the post will be performed synchronously and its timestamp returned. |

**blocks** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | "header" | "section" | "context" | "divider" | "actions" | No | The block type. |

**poll**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `question` | string | Yes | The poll question (1–256 characters). |
| `options` | string[] | Yes | Poll answer options (at least 2, each 1–128 characters). |
| `allowMultipleAnswers` | boolean | No | Whether voters can select multiple options. Defaults to false. |
| `closesAt` | string | No | Optional RFC-3339 datetime when the poll automatically closes. |

## Responses

### 200 - Info retrieved successfully sent

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chat` | TaggedUUID | No | ID of the containing Chat. |
| `threadTimestamp` | integer | No |  |
| `timestamp` | integer | No | Identifying timestamp, present if sync is set. |

**TaggedUUID**:

A UUID prefixed by a tag identifying the specific type of object

#### Example Response

```json
{
  "chat": "D-757dfe66-37b4-4772-baa5-8c86ec68c176",
  "timestamp": 1765602474760032
}
```

### 400 - Bad request. Common causes:
- Invalid chat/group/address ID
- `threadTimestamp` does not correspond to an existing message
- Both `threadKey` and `threadTimestamp` were provided (they are mutually exclusive)
- `threadKey` exceeds 64 characters
- Invalid bot code format
- Multiple content types provided (only one of `text`/`items`, `blocks`, or `poll` allowed)
- `blocks` array exceeds 10 blocks or 8,000 bytes
- Invalid block structure (see [Block Kit guide](/docs/guides/block-kit))
- Interactive buttons sent without an Interactivity URL configured
- Invalid `color` value
- Poll question empty or exceeds 256 characters
- Poll has fewer than 2 options, or an option exceeds 128 characters


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. The bot lacks access to the target:
- Bot is not a member of the chat or group
- Group does not exist in your Roam


### 405 - An unsupported method was requested.

### 413 - Message content exceeds the maximum allowed size.

### 500 - An internal error occured.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/chat-api/chat-post*