# Update a message

`POST /chat.update`

## Description

Edit a previously posted bot message. The updated message can contain plain markdown text or rich [Block Kit](/docs/guides/block-kit) layouts.

The bot must own the message being updated (matched by address ID). Personal access tokens always send as their bot persona and may only edit messages that personal bot posted.

**Access:** Organization and Personal.

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

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chatId` | string | Yes | ID of the chat containing the message. |
| `timestamp` | integer | Yes | Timestamp of the message to update. |
| `threadTimestamp` | integer | No | Thread timestamp, if the message is in a thread. |
| `text` | string | No | Updated 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`. |
| `assetIds` | string[] | No | Array of asset IDs from [`/asset.create`](/docs/api/asset-create) to attach to this message. Each asset must be owned by your app and fully uploaded (processed and ready). Cannot be combined with `blo |
| `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`.  |

**blocks** (array item):

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

## Responses

### 200 - Message updated successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chatId` | string | No | ID of the chat. |
| `timestamp` | integer | No | Timestamp of the updated message. |
| `threadTimestamp` | integer | No | Thread timestamp, if the message is in a thread. |


#### Example Response

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

### 400 - Bad request. Common causes:
- Invalid chat ID
- Invalid or missing `timestamp`
- A `sender` field was provided — the sender is derived from the original message (see [Sender Profiles](/docs/guides/sender-profiles))
- Both `text`/`items` and `blocks` provided (mutually exclusive)
- An `assetId` was not found, not owned by your app, or not a file asset
- An `assetId` is still processing — retry once its upload completes
- `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
- Bot does not own the message


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. The bot lacks access to the target chat.


### 405 - An unsupported method was requested.

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

### 500 - An internal error occurred.

---

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