Sending Messages

Send through an existing Chat when you already know its ID.

Send to an existing Chat

await relay.chats.messages.send(chatId, {
  message: {
    parts: [{ type: "text", value: "The report is ready." }],
    idempotency_key: "message-018f",
  },
});

curl -sS -X POST https://api.relayapp.im/v1/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: message-018f" \
  -d '{
    "message": {
      "parts": [{"type":"text","value":"The report is ready."}]
    }
  }'

Relay returns 202 with the canonical Message projection.

Resolve or create a Chat

Use POST /v1/messages when you know the recipient Handles but not the Chat ID:

const result = await relay.messages.create({
  to: ["alice"],
  message: {
    parts: [{ type: "text", value: "Welcome back." }],
    idempotency_key: "welcome-alice",
  },
});

curl -sS -X POST https://api.relayapp.im/v1/messages \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-alice" \
  -d '{
    "to": ["alice"],
    "message": {
      "parts": [{"type":"text","value":"Welcome back."}]
    }
  }'

The response includes chat_id and created_new_chat. POST /v1/messages can use a link as the first Message. The explicit POST /v1/chats route rejects a first Message that contains a link or an HTTP or HTTPS URL in text.

Send multiple parts

{
  "message": {
    "parts": [
      {"type":"text","value":"Here is the signed report."},
      {"type":"media","attachment_id":"01993d50-d263-7d6b-87ce-90aba89b7815"}
    ]
  }
}

Adjacent text parts are rejected. Combine adjacent text into one part.

Idempotency

Set Idempotency-Key, message.idempotency_key, or both with the same value.

Retry	Result
Same key and same body	Original Message returned
Same key and different body	`409` conflict
No key after an uncertain response	Duplicate send is possible

Limits

Limit	Value
Parts per Message	100
Public URL media parts	40
Text per part	10,000 UTF-16 code units
URL length	2,048 characters
Other Contacts in a Chat	31

Introduction

Getting started

Messaging

Chats

Contacts

Agent events

Webhooks

WebSocket

Platform

Examples

Send to an existing Chat

Resolve or create a Chat

Send multiple parts

Idempotency

Limits

Next steps

​Send to an existing Chat

​Resolve or create a Chat

​Send multiple parts

​Idempotency

​Limits

​Next steps

Send to an existing Chat

Resolve or create a Chat

Send multiple parts

Idempotency

Limits

Next steps