# Reply message

Post a reply to one message as an existing member, in the same channel, forum topic or direct conversation.

- Endpoint: `POST https://api.returning.ai/v1/messages/reply`
- Section: Community / Messaging
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `replyMessage` (Shown in the dashboard as "Reply Message")
- Retries: Not idempotent; check Get Messages before retrying
- Guide: hand-written
- Verified: code, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/messaging/reply-message

## When to use this

- A trader asks a question in a channel and your support account answers it in the thread.
- Your system reacts to a message it read with Get Messages and answers that message directly.
- You reply to a trader's comment in a forum topic.

**Instead:** Use [Send message](https://docs.returning.ai/api-reference/messaging/send-message.md) instead to start a new message that doesn't answer another one.

**Live channel:** A successful call posts the reply straight away, where every member of the channel can see it.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `replyMessage`

Use a Community API key with `replyMessage`, and keep it on your server. The key decides the community, so never send a community ID. A personal user API key with its own reply permission also works; then the reply is posted as the key's owner.

## Behaviour

The reply goes where the original message is: the same channel, the same forum topic, or the same direct conversation. It appears straight away, posted as `sender`. The sender earns the usual XP and reply counts, mentioned members are mentioned, and your community's message webhooks fire.

A reply whose text contains a link is handled as a file: the whole `message` is fetched as a file URL and posted as an attachment. If it can't be fetched, the call fails with `400 Error downloading file`. Leave links out of replies.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `replyMessage`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | `string` | Yes | The message you are replying to, from `data.messages.id` in Get Messages. (Message ID) |
| `sender` | `string` | Yes | The member the reply is posted as, by username or email. Required with a Community API key. With a personal user API key, leave it out to reply as the key's owner. (Username or email of a member) |
| `message` | `string` | Yes | The reply text. Mention a member with `@username`. (At least 1 character) |
| `recipient` | `string` | No | For a reply in a direct-message channel. The other person's username or email. |

### Example request

```bash
curl --request POST \
  --url https://api.returning.ai/v1/messages/reply \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messageId": "66f000000000000000000a21",
    "sender": "support@example.com",
    "message": "Yes, Friday at 14:00 GMT. The link is in the announcements channel."
  }'
```

## Response

A `200` means the reply was posted. The response has no ID; read the channel with Get Messages to find it.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |

### Example response (200)

```json
{
  "status": "success",
  "message": "Message reply successfully"
}
```

## Errors

Validation errors use `meta`, `message`, `detail` and `solution`, with `detail` naming the field. Every other error has `message`, sometimes with `status` or `detail`. None has a machine-readable code, so branch on the HTTP status and read `message`.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | A field is missing or malformed, such as no `messageId`, an empty `message`, or an ID that isn't 24 hex characters (`detail` names the field). `Sender field is required` means you used a Community API key without `sender`. `Error downloading file` means the text contains a link that couldn't be fetched (see Behaviour). Nothing was posted. |
| 401 | - | The key is missing (`Invalid token`), unknown (`Invalid API key`) or expired, or it lacks `replyMessage` (`Your API key does not have permission to access this action`). Add the permission in Settings > Integration > API Keys. |
| 403 | - | The sender can't reply here: a personal user API key whose owner can't post in the channel, or someone who isn't part of the direct conversation. Nothing was posted. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | `message` says which: `Message not found` (check `messageId` with Get Messages), `User not found` (no member has that `sender`), `Recipient not found`, or `Channel not found`. Nothing was posted. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | The reply failed, or the key could not be checked (`Authentication failed`). The reply may already be posted, so check Get Messages before you retry. |

**Retries:** This endpoint doesn't accept an `Idempotency-Key`, and every successful call posts a new reply. After a timeout or a `500`, read the channel with Get Messages and reply again only when your reply isn't there. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get messages](https://docs.returning.ai/api-reference/messaging/get-messages.md): `GET /v1/messages`. Confirm the reply is in the channel. This endpoint doesn't return the reply's ID.
- [React to a message with React Message](https://docs.returning.ai/api-reference/messaging/react-message.md): `POST /v1/messages/react`.