# Cancel a scheduled message

`POST /chat.scheduled.cancel`

## Description

Cancels a pending message scheduled via [`/chat.post`](/docs/api/chat-post)'s
`sendAt`, so it will never be delivered. Pending scheduled messages can be
discovered with [`/chat.scheduled.list`](/docs/api/chat-scheduled-list).

Only the credential's bot identity that scheduled the message may cancel it. A
`scheduledMessageId` scheduled by a different identity — or one that never
existed — returns `scheduled_message_not_found`; the endpoint does not reveal
whether such an id exists. Canceling a message that has already been sent
returns `scheduled_message_already_sent`.

Cancellation is best-effort once the scheduled send time arrives: delivery of a
due message begins in the seconds after its `sendAt` boundary, and a cancel
issued inside that window may return success while the message is still
delivered. Cancel ahead of the scheduled time to be safe.

**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 |
|----------|------|----------|-------------|
| `scheduledMessageId` | string | Yes | The id returned by `/chat.post` when the message was scheduled. |

## Responses

### 200 - Scheduled message canceled; it will not be delivered.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `scheduledMessageId` | string | No | The canceled scheduled message id. |


#### Example Response

```json
{
  "scheduledMessageId": "0197f9f0-5cc1-7d07-8a12-9e65a8a0c1b9"
}
```

### 400 - Bad request. Common causes:
- Missing `scheduledMessageId` (`missing_parameter`)
- Malformed JSON body (`invalid_json`)


### 401 - Presented invalid authentication credentials.

### 403 - Token lacks a required scope (`missing_scope`).

### 404 - The scheduled message could not be found, or was scheduled by a different credential (`scheduled_message_not_found`).

### 405 - An unsupported method was requested.

### 409 - The message was already sent (or its delivery has begun) and can no longer be canceled (`scheduled_message_already_sent`).

### 500 - An internal error occured.

---

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