> ## Documentation Index
> Fetch the complete documentation index at: https://docs.my-aichatbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Post a reply (response URL)

> Reply to an event within 45 minutes. The token in the URL is the key.

Send Block Kit to the `response_url` from any event, and the message lands in the conversation that created the event. No `Authorization` header: having the URL is your permission.

## Path parameters

**token** `string` *required*

The token baked into the event's `response_url`. Use the URL exactly as we sent it. Never build one yourself.

## Body

`application/json`. Any [Block Kit shape](https://docs.my-aichatbot.com/block-kit/overview.md#shortcuts) we accept, up to 256 KB and 10 messages.

**messages** `array`

One to ten messages. Each has `blocks` (1 to 25) and optional `mid` and `metadata`. Shortcuts such as `{ "text": "…" }` are expanded for you.

**mid** `string`

Your own id for the message, matching `^[a-zA-Z0-9_.:-]{1,64}$`. Send it again and the message is **replaced** instead of duplicated. See [Updating messages](https://docs.my-aichatbot.com/sending-messages/updating-messages.md).

> [!NOTE]
>
> A [`page` block](https://docs.my-aichatbot.com/block-kit/blocks/page) in the body publishes a hosted Page in the same call, as long as the conversation is an internal one. To publish without a conversation at all, use the [Pages API](https://docs.my-aichatbot.com/api-reference/pages/create-page.md).

## Response

**ok** `boolean`

`true` on success.

**messages** `array`

One handle per message in your body, in order.

**properties**

**message\_id** `string`

The stored message.

**mid** `string | null`

The `mid` you sent, if any.

**updated** `boolean`

`true` when the `mid` matched an existing message and replaced it.

```bash curl theme={null}
curl -X POST "$RESPONSE_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{ "label": "Download", "url": "https://example.com/r.pdf" }]
  }'
```

```javascript Node.js theme={null}
await fetch(responseUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mid: 'reply-evt_7f3a',
    text: 'Your report is ready 📊',
    buttons: [{ label: 'Download', url: 'https://example.com/r.pdf' }]
  })
})
```

```python Python theme={null}
import requests

requests.post(response_url, json={
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{"label": "Download", "url": "https://example.com/r.pdf"}],
})
```

```json 200 OK theme={null}
{
  "ok": true,
  "messages": [
    { "message_id": "0f8c…", "mid": "reply-evt_7f3a", "updated": false }
  ]
}
```

```json 410 Expired theme={null}
{
  "ok": false,
  "error": {
    "code": "RESPONSE_URL_EXPIRED",
    "message": "This response_url has expired — use the bot-level API."
  }
}
```

## Token rules

| Rule | Detail |
| - | - |
| Lifetime | 45 minutes from when the event was created. |
| Reuse | Multi-use until it expires. Post several messages, or update one many times. |
| Retries | Every retry of one event carries the exact same `response_url`. |
| Scope | Only the conversation that created the event. |
| Rate limit | 30 requests per minute per token. |

## Errors

| Status | Code | Meaning |
| - | - | - |
| `401` | `token_invalid` | The token is broken or has a bad signature. |
| `402` | `MESSAGE_CAP_REACHED` | The workspace's monthly message limit is used up. |
| `404` | `conversation_not_found` | The conversation no longer exists. |
| `409` | `conversation_taken_over` | A person has taken over. The bot is locked out. |
| `410` | `RESPONSE_URL_EXPIRED` | Past 45 minutes. Use an [API key](https://docs.my-aichatbot.com/api-reference/post-message.md) instead. |
| `413` | `PAYLOAD_TOO_LARGE` | Body over 256 KB. |
| `422` | `EMPTY_BODY` | Nothing to post. An empty body is an error here, unlike a webhook reply. |
| `422` | `FRAMEWORK_DEFAULT_BODY` | You posted `Accepted`, `OK`, or similar. |
| `422` | `BLOCK_VALIDATION_FAILED` | Bad Block Kit. The `issues` list shows each problem. |
| `429` | `rate_limited` | Over 30 per minute. Wait for `retry_after` seconds. |
| `429` | `UPDATE_LIMIT_REACHED` | One `mid` was updated more than 60 times. |
| `500` | `PERSIST_FAILED` | We could not store the message. Retry with the same `mid`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.