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

# Message Parts

> Build ordered text, media, link, and interaction parts for a Message.

A message carries 1 to 100 parts in order, each with a `type`. A `text` part carries `value`, up to 10,000 UTF-16 code units, and may carry one structured mention.

A `media` part names a file: the `attachment_id` of a completed Attachment, or one public HTTPS URL up to 10 MiB (10,485,760 bytes), never both. A `link` part carries one URL and must be the only part in its message. A `place` part carries one point, with an optional name and address; [Places](https://docs.staging.relayapp.im/messages/places.md) covers it.

Position matters. `part_index` is the zero-based place of a part in the array, and replies and reactions use it to point at one exact part. Text and media can be mixed in any order, but two text parts may not sit next to each other; combine them into one.

## Create a Message body

Send a text part followed by an uploaded file:

**Preview**

A text part, then a PDF drawn as a document card; tap the card

**JSON**

```json theme={null}
{
  "message": {
    "parts": [
      {"type":"text","value":"Here is Shannon's paper on communication."},
      {"type":"media","attachment_id":"01993d50-d263-7d6b-87ce-90aba89b7815"}
    ]
  }
}
```

The app draws a photo or a video in the chat, and any other file as a document card with its name and size. A tap on the card opens the file.

The text part is `part_index` 0 and the media part is 1. To send a hosted file instead of an upload, replace `attachment_id` with `url`. To send a URL as a preview, send it as a link part on its own. A text part that is only one web address also shows its preview. A web address with words around it stays in the text bubble, underlined and tappable; see [Rich link previews](https://docs.staging.relayapp.im/messages/rich-link-previews.md).

[Upload attachments](https://docs.staging.relayapp.im/messages/attachments.md) covers files you hold locally, [Import media from a URL](https://docs.staging.relayapp.im/messages/import-media.md) covers hosted files, and [Mentions](https://docs.staging.relayapp.im/messages/mentions.md) covers the `mention` fields on a text part.

For Markdown source in `value`, see [Markdown syntax and current rendering behavior](https://docs.staging.relayapp.im/messages/send.md#markdown).

## Add interactions

Interactions add controls that agents can send directly in the chat. Include them in the Message's `parts` array; each interaction defines its own request format and behavior. See [Interactions](https://docs.staging.relayapp.im/interactions/index.md) for the available formats and examples.

## Read parts in a response

A part you read back carries more than the part you sent. Most parts gain `reactions`, the current reactions on that part or `null`; a `selection` part's `reactions` is always `null`, and a `selection_response` part has no `reactions` key. A media part gains the Attachment ID, a download URL, and the file's metadata; a text part gains `mentions`; a `selection` part gains [`has_responded`, `selected_values`, and `selected_ids`](https://docs.staging.relayapp.im/interactions/selection#read-whether-someone-answered); a `payment` part gains the request's amount, title and [`status`](https://docs.staging.relayapp.im/interactions/payments#status). A `payment_receipt` part is the payer's receipt, written only by Relay. A [`location_request`](https://docs.staging.relayapp.im/chats/location) part is your agent's request for a location, and a `location` part is the person's share: its `state` and times, never a position. A [`place`](https://docs.staging.relayapp.im/messages/places) part comes back as it was sent, and so do a [`rich_card` and a `carousel`](https://docs.staging.relayapp.im/interactions/rich-cards); a [`suggestion_response`](https://docs.staging.relayapp.im/interactions/rich-cards#receive-a-reply) part gains the reply's `label` and has no `reactions` key. A [`data`](https://docs.staging.relayapp.im/interactions/custom-cards) part holding a custom card comes back with every message applied to that card, in order.

Relay also returns parts of `type: "system"` for visible chat events such as a participant joining or a group being renamed. Your agent cannot send a system part.

A [`form`](https://docs.staging.relayapp.im/interactions/form#read-whether-someone-answered) part gains viewer-specific `has_responded` and `answers`, with `reactions: null`. A `form_response` part carries answers keyed by field ID and has no `reactions` key.

## When it fails

| Status | Code | Cause |
| - | - | - |
| `400` | [1005](https://docs.staging.relayapp.im/api-reference/errors.md#1005) | The array is empty or over 100 parts, two text parts are adjacent, a link is not alone, a media part names both inputs or neither, text is over 10,000 code units or text is over 10,000 code units. |
| `404` | [2007](https://docs.staging.relayapp.im/api-reference/errors.md#2007) | The `attachment_id` names an Attachment that is not complete. |
| `413` | [2006](https://docs.staging.relayapp.im/api-reference/errors.md#2006) | A media `url` points at a file over 10 MiB. |
| `422` | [2006](https://docs.staging.relayapp.im/api-reference/errors.md#2006) | A media `url` failed the public-network, redirect, or response checks. |

## Next steps

* [Send a message](https://docs.staging.relayapp.im/messages/send.md)
* [Upload attachments](https://docs.staging.relayapp.im/messages/attachments.md)
* [Send a rich link preview](https://docs.staging.relayapp.im/messages/rich-link-previews.md)
* [Mention a participant](https://docs.staging.relayapp.im/messages/mentions.md)
* [Send a place](https://docs.staging.relayapp.im/messages/places.md)


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