# 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 are not supported for this endpoint.

**Access:** Organization only.

**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` | string | Yes | Tagged 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`. |
| `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 |
|----------|------|----------|-------------|
| `chat` | TaggedUUID | No | Tagged ID of the chat. |
| `timestamp` | integer | No | Timestamp of the updated message. |
| `threadTimestamp` | integer | No | Thread timestamp, if the message is in a thread. |

**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 ID
- Invalid or missing `timestamp`
- Both `text`/`items` and `blocks` provided (mutually exclusive)
- `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
- Personal access token used (not supported)
- 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 occured.

---

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