# Send a Roam message

`POST /chat.sendMessage`

## Description

Sends the given message to the specified recipients. At this time, we only
support sending to a single group recipient. You can obtain the group ID on the "Group
Settings" page. That means `recipients` will always be a single-element array containing
a single UUIDv4.

The `sender` JSON object contains three (optional) string fields: `id`, `name`, and
`imageUrl`. The `id` is an internal name of the bot you wish to send as, `name` is the
user-visible bot name (that is seen when viewing groups), and `imageUrl` is the image
URL of the bot. Generally, you only need to specify `id` and `name` (e.g.
`datadog` as `id` and `Datadog Alerts` as `name`). If omitted, the ID and
sender are inferred to be the API client name.

## Message Text Format

At this time, we do not fully support standard Markdown, but support is forthcoming. To
indicate a line break, you must use TWO new line characters in the message (e.g.. `\n\n`).

**Access:** Organization only.

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

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `recipients` | string[] | Yes |  |
| `text` | string | Yes |  |
| `markdown` | boolean | No | Text is markdown by default. If this is set to false, markdown interpretation will be disabled. |
| `sender` | MessageSender | No |  |

**MessageSender**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes |  |
| `name` | string | No |  |
| `imageUrl` | string | No |  |

### Example Request

```json
{
  "recipients": [
    "757dfe66-37b4-4772-baa5-8c86ec68c176"
  ],
  "sender": {
    "id": "datadog",
    "name": "Datadog"
  },
  "text": "Test message"
}
```

## Responses

### 200 - Message successfully sent

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chatId` | string | No |  |
| `status` | string | No |  |


#### Example Response

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

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

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