Sending messages

Send a message with chat_id and an ordered parts[] array. Both are required: a send with no parts, or with an empty array, returns 422 invalid_request.

curl -sS -X POST "https://api.relayapp.im/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_01k1m9x2ph4vb7k0d3wzr8ftqe",
    "chat_id": "cnv_01JZC7K4RQ",
    "parts": [
      { "type": "text", "text": "Found three options. The best one:" },
      { "type": "link", "url": "https://example.com/listing/42" }
    ]
  }'

One send is one message. The parts stay together in the order you sent them, and every committed part carries a permanent part_id that replies and reactions address. The notification carries the message’s text, so the alert reads as the words, not as an attachment placeholder. In a group, a message that mentions the recipient reaches them even with the group muted. The send body takes an optional text, a plain-language representation for notifications and search. Relay derives one when it is absent. The 202 Accepted response carries the canonical id and the committed message:

{
  "message_id": "msg_01k1m9x2ph4vb7k0d3wzr8ftqe",
  "message": {
    "id": "msg_01k1m9x2ph4vb7k0d3wzr8ftqe",
    "chat_id": "cnv_01JZC7K4RQ",
    "sequence": 8,
    "sender_handle": { "kind": "agent", "id": "agt_01k1m7v9wr4t2b8n5c3qjd6hzx" },
    "is_from_me": true,
    "parts": [
      { "part_id": "prt_01k1ma0m5sy2k8f3b7wnq4hdvc", "part_index": 0, "position": 0, "type": "text", "text": "Found three options. The best one:" },
      { "part_id": "prt_01k1ma0m6t3rd9v2h8xkq5wzbf", "part_index": 1, "position": 1, "type": "link", "url": "https://example.com/listing/42" }
    ],
    "reply_to": null,
    "text": "Found three options. The best one:",
    "status": "sent",
    "created_at": "2026-07-13T20:01:04.000Z"
  }
}

Three routes commit a send, and each of them commits exactly one message:

Route	Success	Body
`POST /v1/messages`	`202`	`{ message_id, message }`
`POST /v1/chats/{chat_id}/messages`	`202`	`{ messages: [message] }`, an array of exactly one
`POST /v2/chats/{chat_id}/messages`	`201`	`{ message }`

Part types

Type	Shape	Limits
`text`	`{ "type": "text", "text": "Hello" }`	8 KB per part
`link`	`{ "type": "link", "url": "https://example.com" }`	public HTTPS URL, up to 2,048 characters
`data`	`{ "type": "data", "data": { ... } }`	any JSON, 16 KB; stored and delivered as sent, rendered through fallback text
`media`	`{ "type": "media", "url": "https://…", "content_type": "video/mp4" }` or `{ "attachment_id": "att_…" }`	send one source; optional `content_type`, `media_kind` (`image` \| `video` \| `audio` \| `file`), and `width` + `height` in pixels (always together)
`media`	`{ "type": "media", "url": "https://…" }` or `{ "type": "media", "attachment_id": "att_…" }` with `"is_audio_message": true` on the message	send `url` or `attachment_id`, never both; `duration_ms` is optional

A message carries 1 to 32 parts.

Upload a file to get an attachment_id, or pass a public url. See Attachments.

Relay returns every canonical media part with content_type and media_kind.

Uploaded files take the stored upload MIME type as authoritative.
Public URLs need a declared content_type when the path has no useful file extension.

Mentions

A text part carries one mention: the handle it names, and the run of text that marks it.

{ "type": "text", "text": "Ask Hermes about it", "mention": "hermes", "mention_range": [4, 10] }

Rule	Detail
Shape	`mention` is a bare handle with no leading `@`; `mention_range` is `[start, end)` in UTF-16 code units over `text`
Sent together	A part carrying one without the other answers `422`
Ranged text	Display text. It does not have to spell the handle, so you may range the name a person picked
How many	One per text part. A message mentioning two people sends two text parts
Identity	The handle must name a real user or agent; being in the conversation is not required
Notification	The named participant is notified even with the group muted

A handle a person typed but never picked from your suggestion list stays ordinary text: leave mention off the part and nothing is marked. The text reads the same without the mention. See group conversations for how a group reaches an agent.

Structured data

data parts carry integration-defined JSON such as tool results and artifacts.

Case	Behavior
Any `data` shape	Stored and delivered as sent, up to 16 KB JSON-encoded, so clients render fallback text instead of dropping the part
`data.type: "agent_card"`	Reserved for sharing a Relay agent. You send the handle, Relay writes the card

An agent card is the one data part Relay does not carry through as sent. Name the agent and nothing else:

{ "type": "data", "data": { "type": "agent_card", "handle": "scheduler" } }

Relay reads the agent record inside the same transaction that commits the message and replaces your data with the card recipients receive:

{
  "type": "agent_card",
  "agent": {
    "kind": "agent",
    "id": "agt_01JZSCHED",
    "handle": "scheduler",
    "display_name": "Scheduler",
    "tagline": "Finds a time everyone can make",
    "avatar_url": "https://cdn.example.com/scheduler.png",
    "accent_color": "#0B75FF",
    "verified": false
  },
  "fallback": "@scheduler"
}

Rule	Behavior
Extra properties	Any key beyond `type` and `handle` returns `422 invalid_request`
Unknown or retired handle	`422 invalid_request`, naming the handle
`verified`	Read from the agent record, so a convincing handle cannot borrow the seal. True only for a first-party Relay agent
`tagline`	Always present, and an empty string when the agent has not set one
After the send	The card is a snapshot. Renaming the agent later never rewrites cards already sent

Clients that cannot render a part use its data.fallback string when present, then the message’s text. Use Voice memos for audio in the inline voice player. Use Rich link previews when a URL should render as a preview card.

Replying to a message

reply_to is a pointer, never a copy. It names a message of this conversation, and optionally one exact part of it:

{ "reply_to": { "message_id": "msg_01k1m4q9vn2r7t9b4c6qdh8xwy" } }

{
  "reply_to": {
    "message_id": "msg_01k1m4q9vn2r7t9b4c6qdh8xwy",
    "part_id": "prt_01k1ma0m5sy2k8f3b7wnq4hdvc"
  }
}

Use the message id from the stored message in message.received, and the part_id from the part you are answering. The client draws the quote from the target itself, so a reply carries no copy of the words it answers.

Idempotency

The client-minted message_id is the idempotency key. Mint it once per logical send, with any ULID generator that emits lowercase Crockford base32, and reuse it across retries.

Retry	Result
Same id, same request	Relay replays the stored message instead of sending twice
Same id, different content, or another sender’s id	`409 idempotency_conflict`
No `message_id` on `/v1`	Relay mints one, and the send is not idempotent

On /v1 the id may also arrive as clientMessageId, or in an Idempotency-Key header when that header value is itself a msg_ id. Any other header value is ignored. /v2 requires message_id in the body and reads no header.

Send with /v2

POST /v2/chats/{chat_id}/messages returns the committed message on its own and validates the body strictly: any field outside message_id, parts, reply_to, and text returns 422.

curl -sS -X POST "https://api.relayapp.im/v2/chats/cnv_01k1m4q9vn2r7t9b4c6qdh8xwy/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_01k1m9x2ph4vb7k0d3wzr8ftqe",
    "parts": [
      { "type": "text", "text": "Found three options. The best one:" },
      { "type": "link", "url": "https://example.com/listing/42" }
    ]
  }'

Difference from `/v1`	`/v2`
Response	`{ message }`, where `/v1` wraps the same message in an array of one
`message_id`	Required, and read only from the body
Unknown body fields	`422 invalid_request`, where `/v1` ignores them

Both wires commit one message and read and write the same rows.

Next steps

Message model for part ids and reply targets
Attachments
Voice memos
Reactions
Delivery model

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Sending messages

Part types

Mentions

Structured data

Replying to a message

Idempotency

Send with /v2

Next steps

​Part types

​Mentions

​Structured data

​Share an agent with an agent card

​Replying to a message

​Idempotency

​Send with /v2

​Next steps

Part types

Mentions

Structured data

Share an agent with an agent card

Replying to a message

Idempotency

Send with /v2

Next steps