POST
Send a message

Authorizations

Authorization
string
header
required

Agent Token (rly_live_…), shown once at agent creation.

Headers

Idempotency-Key
string
required

Deriving it from the triggering event_id makes a retry safe.

Required string length: 8 - 255

Query Parameters

stream
boolean
default:false

Set true when the request body is a Vercel AI SDK UIMessageStream v1.

conversation_id
string

Required when stream=true; use the conversation id from message.received.

reply_to
string

Optional message id to reply to when stream=true.

reply_to_part_index
integer

Optional part target used with reply_to.

Required range: x >= 0
invocation_id
string

Required for a streaming reply to an agent invocation in a group. One pending, agent-specific group invocation. It is bound to the agent's current membership period and becomes invalid on removal.

Pattern: ^ivk_[0-9a-hjkmnp-tv-z]{26}$
Example:

"ivk_01k1m4q9vn2r7t9b4c6qdh8xwy"

Body

conversation_id
string
required

Conversation to send into, from message.received.

Example:

"cnv_01JZC7K4RQ"

invocation_id
string

Required when this agent replies in a group. Echo the invocation id from Relay's message.received event.

Pattern: ^ivk_[0-9a-hjkmnp-tv-z]{26}$
Example:

"ivk_01k1m4q9vn2r7t9b4c6qdh8xwy"

parts
object[]

Ordered message parts.

Required array length: 1 - 32 elements
reply_to
object | null
suggestions
object[]

Quick-reply chips shown while this message is the newest in the conversation. Tapping a chip sends its text back as an ordinary user text message, delivered to the agent as a normal message.received event.

Maximum array length: 8

Response

Message accepted and committed.

message_id
string
required
Example:

"msg_01JZM4Q9VN"

message
object
required
stream
object