Conversation history

Read conversation history after a restart, on a cold start, or when rebuilding a prompt window.

curl -sS "https://api.relayapp.im/v1/chats/cnv_01JZC7K4RQ/messages?limit=50" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

Messages return newest first:

{
  "messages": [
    {
      "id": "msg_01JZM4Q9VN",
      "chat_id": "cnv_01JZC7K4RQ",
      "sequence": 2,
      "sender_handle": { "kind": "agent", "id": "agt_01JZRELAY" },
      "is_from_me": true,
      "parts": [{ "part_index": 0, "type": "text", "text": "Tomorrow at 2:00 PM works." }],
      "reply_to": { "message_id": "msg_01JZM3T8AH" },
      "reactions": [],
      "text": "Tomorrow at 2:00 PM works.",
      "status": "read",
      "edited_at": "2026-07-12T01:21:12.000Z",
      "revisions": [
        {
          "parts": [{ "part_index": 0, "type": "text", "text": "Tomorrow at 1:00 PM works." }],
          "text": "Tomorrow at 1:00 PM works.",
          "replaced_at": "2026-07-12T01:21:12.000Z"
        }
      ],
      "created_at": "2026-07-12T01:21:08.000Z"
    }
  ]
}

Field	Contents
`parts[]`	The message parts, in order
`sequence`	Position inside this conversation
`is_from_me`	`true` when the authenticated caller sent it. Read direction from this field, never from comparing `sender_handle.id`
`reply_to`	The targeted message and part, or `null`
`reactions`	Reactions on the message
`revisions`	Prior `parts` and `text` snapshots, oldest to newest. Empty until the first edit
`edited_at`	Present after the first edit
`status`	Receipt projection: `sent`, `delivered`, or `read`

An unsent message keeps its place in sequence order, but projects as a bare tombstone:

{
  "id": "msg_01K1M9UNSENT",
  "chat_id": "cnv_01JZC7K4RQ",
  "sequence": 3,
  "sender_handle": { "kind": "user", "id": "usr_01JZU1F0BD" },
  "status": "deleted",
  "created_at": "2026-07-12T01:21:10.000Z"
}

Tombstones do not expose parts, fallback text, reactions, or revisions.

Pagination

limit accepts 1 to 100 and defaults to 50. To page backward, pass your lowest sequence as before_sequence.

curl -sS ".../messages?before_sequence=2&limit=50" ...

An empty messages array means you have reached the start of the conversation.

In a group, history is your invocations

A group agent does not read the group transcript. This route returns only the messages inside that agent’s own invocations: each message that invoked it, and each message it committed in reply, including every message of a split reply batch. Messages between other participants never appear, and a group the agent has never been invoked in returns an empty messages array. In a 1:1 conversation the agent reads the whole history its membership covers. Build a group prompt window from what message.received delivers plus this scoped history. Treat an empty page as the start of your scope, not as an empty conversation.

Notes

History stays readable while the agent participates in the conversation. Any other case returns 403 forbidden.
sequence orders messages within one conversation. It has no relationship to a webhook event_id.
History is the recovery path after an event gap or an uncertain delivery.

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Conversation history

In a group, history is your invocations

Notes

Next steps

​Pagination

​In a group, history is your invocations

​Notes

​Next steps

Pagination

In a group, history is your invocations

Notes

Next steps