# Send a message (Legacy)

`POST /chat.sendMessage`

## Description

**Legacy:** Prefer [`/chat.post`](/docs/api/chat-post). This endpoint is maintained for backwards compatibility only.

Send a markdown-formatted text message to a single group, addressed by `recipients` (a one-element array containing the group ID). New integrations should use [`/chat.post`](/docs/api/chat-post), which also supports DMs, threads, Block Kit, and polls.

The optional `sender` object follows the same semantics as `/chat.post` — see the [Sender Profiles guide](/docs/guides/sender-profiles).

**Required scope:** `chat:send_message`

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `recipients` | string[] | Yes | Destination group, as a single-element array containing one group ID (UUID). Exactly one recipient is required: zero recipients returns 400, and more than one is not currently supported (also 400).  |
| `text` | string | Yes | Message text in GitHub-flavored markdown. Required. |
| `markdown` | boolean | No | Text is markdown by default. If set to false, markdown interpretation will be disabled. |
| `items` | string[] | No | Array of Item IDs (UUIDs) to attach to this message. |
| `sender` | Sender | No |  |

**Sender**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | No | Code of a configured bot persona to author the message as (trimmed, case-insensitive). Omitted, empty, or `_` posts as the app's root identity. Unconfigured ids are accepted and ignored — supplying an |
| `name` | string | No | Display name override for this message only (max 128 characters). Does not rename the app or persona.  |
| `imageUrl` | string | No | Avatar URL override for this message only. Must be an absolute HTTP(S) URL.  |

### Example Request

```json
{
  "recipients": [
    "757dfe66-37b4-4772-baa5-8c86ec68c176"
  ],
  "text": "Hello team!"
}
```

## Responses

### 200 - Message sent successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `status` | string | Yes | Always `ok` on success. |
| `chatId` | string | Yes | ID of the chat where the message was posted. |


#### Example Response

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

### 400 - Bad request. Common causes:
- Missing `text` (`No text provided`)
- No recipient specified (`No recipients specified`)
- More than one recipient (`More than one recipient is not supported`)
- Recipient is not a valid group UUID (`Invalid group ID`)
- `sender.name` exceeds 128 characters, or `sender.imageUrl` is not an absolute HTTP(S) URL


### 401 - Invalid authentication credentials, or the target group belongs to a different account.

### 403 - Missing required scope (`chat:send_message`).

### 413 - Message text exceeds the maximum size (8000 bytes).

### 500 - An internal error occurred.

---

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