Read receipts

Call responding when an inbound message starts a normal response:

curl -sS -X POST "https://api.relayapp.im/v1/chats/cnv_01JZC7K4RQ/responding" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_01JZM3T8AH",
    "label": "Thinking…"
  }'

Relay validates the target, commits Read, then sends chat.typing_indicator.started. A failed validation or receipt write sends no typing signal. Retries are safe. Read is idempotent. Typing refreshes its expiry. Groups use the same correlation as direct chats: message_id is the id of the inbound message from the message.received event you are responding to.

{
  "message_id": "msg_01JZM3T8AH",
  "label": "Checking the schedule…"
}

Four separate facts

State	Meaning
Sent	Relay stored the message
Delivered	The recipient runtime durably accepted the message
Read	The recipient consumed or visibly viewed the message
Typing	The recipient sent a temporary, independent signal

Read implies Delivered. Delivery never starts typing. Typing alone never marks a message Read.

Delivered and Read answer different questions

The two rungs report two different things about your agent, and they are owned by two different parties.

Rung	Question it answers	Who records it
Delivered	Is the agent alive and does it have the message	The transport, automatically
Read	Is the agent engaged with the message	You, through `/read` or `/responding`

Delivered is not something you write code for. Relay takes it from the transport itself, so it arrives the moment your endpoint accepts the event and it cannot be faked, delayed, or switched off. An agent that is reachable is Delivered. An agent that is down is not. Read is the rung you control, and it means the agent has taken the message up. Nothing about either rung says the reply is finished.

Delivered is stamped from your webhook response, so anything your handler does before answering is time the sender spends watching a message with no receipt under it. A handler that runs a model call before its 2xx turns a slow turn into a slow Delivered. Answer first, then work. See Webhooks.

Delivered + typing is valid during proactive activity. Ordinary response typing must identify the consumed message through /responding.

Consume without replying

Use /read when your backend consumes a message without starting a response:

curl -sS -X POST "https://api.relayapp.im/v1/chats/cnv_01JZC7K4RQ/read" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message_id": "msg_01JZM3T8AH" }'

/read, /delivered, and /responding all answer with the watermark after the call:

{
  "receipt": {
    "message_id": "msg_01JZM3T8AH",
    "chat_id": "cnv_01JZC7K4RQ",
    "through_sequence": 12,
    "recipient": { "kind": "agent", "id": "agt_01JZRELAY" },
    "status": "read",
    "delivered_at": "2026-07-13T20:02:09.000Z",
    "read_at": "2026-07-13T20:02:11.000Z"
  },
  "advanced": true
}

Rule	Behavior
Marking one message Read	Covers every earlier message in the conversation
Repeating or targeting an older message	Returns the current receipt with `advanced: false`
Target	Must be an accessible message from another participant
Group target	Must match this agent’s invocation scope
Past 240 receipts a minute	`429 rate_limited`, with `Retry-After` in seconds

/responding spends from the read-receipt budget and the typing budget in the same call. Watermarks make that cheap to live with: mark the newest message you consumed rather than every message behind it.

Record delivery

Relay records Delivered when a subscribed webhook accepts a message.

Action	Relay records Delivered
Webhook	After your endpoint answers `2xx`
`/delivered`	When you call it

Webhook consumers get Delivered from Relay and need no extra call. For a webhook, the receipt is stamped when your response returns, so the speed of your handler is the speed of the sender’s Delivered. Acknowledge as soon as the event is verified and safely in hand, and do the work after:

Verify the signature

Reject anything that fails, with 401.

Skip a replay

Delivery is at least once. An event_id you already accepted is answered 200 and dropped.

Hand the event somewhere durable

A queue, a job table, or a background runtime. This step is what makes the next one honest.

Answer 2xx

The sender sees Delivered from here.

Do the work

Call /responding, run your model, send the reply.

A 2xx ends Relay’s delivery, so it will not send the event again. Retries move from Relay to you, which is why step 3 comes before step 4. Derive your reply’s idempotency key from the inbound event_id so your own retry replays the same send instead of posting twice. Call /delivered only when you explicitly need to stamp delivery at a point you control, such as after you durably enqueue the message:

curl -sS -X POST "https://api.relayapp.im/v1/chats/cnv_01JZC7K4RQ/delivered" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message_id": "msg_01JZM3T8AH" }'

Send it on ingest, before /read or /responding. Recording Read advances the delivered watermark as well, so a /delivered call that arrives after a Read for the same message answers advanced: false and emits no delivery event.

Order matters more than frequency. One /delivered on ingest gives the sender Sent, Delivered, then Read. The same call after /responding changes nothing the sender can see.

Track your replies

Relay emits two events as your reply moves through the conversation.

Event	Emitted when
`message.delivered`	A user’s runtime durably accepts the agent’s message
`message.read`	The user visibly reads through it

Both carry through_sequence. Conversation history projects each outbound message as sent, delivered, or read.

Next steps

Typing indicators for proactive starts and stops
Event types for receipt payloads
Delivery model for the full lifecycle

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Read receipts

Four separate facts

Delivered and Read answer different questions

Consume without replying

Record delivery

Track your replies

Next steps

​Four separate facts

​Delivered and Read answer different questions

​Consume without replying

​Record delivery

​Track your replies

​Next steps

Four separate facts

Delivered and Read answer different questions

Consume without replying

Record delivery

Track your replies

Next steps