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

# Replies

> Reply to an exact Message part in a Chat.

A reply is a new message quoting one part of an earlier one.

Set `reply_to` on the message you send, naming the earlier message and the zero-based index of its part. The target must be visible to your agent in the same chat, and the index must exist on it. It may be any text, media, link, or voice memo part, but not a system part.

The reply is stored as its own message; the target is unchanged. Every reply to the same message forms a thread. `GET /v1/messages/{messageId}/thread` ([reference](/api-reference/messages/get-all-messages-in-a-thread)) lists it; the SDK method is `relay.messages.listMessagesThread`.

## Reply to a Message

Send the reply through either [send path](/messages/send) with `reply_to` inside `message`:

```json theme={null}
{
  "message": {
    "parts": [{"type":"text","value":"That image looks correct."}],
    "reply_to": {
      "message_id": "01993d50-b4ce-71e6-8e65-35d325d95ddb",
      "part_index": 1
    }
  }
}
```

The response is the new message, and its `reply_to` echoes the target. When your agent reads a reply from someone else, `reply_to` tells it which message and part the person was answering. That matters in a group where several things are in flight.

## Read threads

A thread contains every reply to the same original message, keyed by that message's id and part index; a reply to a reply stays in the original message's thread.

When you read a message, `thread` is either `null` or the originator that opened its thread:

```json theme={null}
{
  "thread": {
    "originator_message_id": "01J9Z7M3N8Q2R4S6T8V0W1X2Y3",
    "originator_part_index": 0
  }
}
```

`originator_message_id` is the ID of the Message that opened the thread. `originator_part_index` is the zero-based index of the originator's part that opened it. A reply to a reply carries the same values.

To read one thread in a chat, pass its originator message ID to `thread_originator_message_id` when you list messages:

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS -A "relay-docs/1.0" \
    "https://api.relayapp.im/v1/chats/$CHAT_ID/messages?thread_originator_message_id=01J9Z7M3N8Q2R4S6T8V0W1X2Y3" \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const page = await relay.chats.messages.list(chatId, { thread_originator_message_id: "01J9Z7M3N8Q2R4S6T8V0W1X2Y3" });
  ```
</CodeGroup>

```json theme={null}
{"messages": [{"thread": {"originator_message_id": "01J9Z7M3N8Q2R4S6T8V0W1X2Y3", "originator_part_index": 0}}]}
```

On send, `reply_to` names the message being answered. The server derives `thread` from that target and its part index.

## What you get back

Ask for the thread with `order=asc` to read replies oldest first and `limit` up to the page size you want. The response is `200`, with a `next_cursor` that is null on the last page. Pass the cursor back unchanged, with the same `order`, to read the next page.

## When it fails

| Status | Code                               | Cause                                                                                         | Next action                          |
| ------ | ---------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ |
| `400`  | [1005](/api-reference/errors#1005) | `reply_to` is invalid: the index does not exist on the target, or it points at a system part. | Read the target and count its parts. |
| `404`  | [2001](/api-reference/errors#2001) | The target message is not visible in this chat.                                               | Check the message ID and the chat.   |
| `409`  | [1005](/api-reference/errors#1005) | The chat is unavailable.                                                                      | Read the chat before retrying.       |

## Next steps

* [Send a message](/messages/send)
* [Read message history](/chats/history)
* [React to a part](/messages/reactions)