Event types

Every event uses the same envelope:

{
  "event_id": "evt_01JZE9M2XW",
  "event_type": "message.received",
  "agent_id": "agt_01JZRELAY",
  "created_at": "2026-07-12T01:21:03.000Z",
  "data": { }
}

event_id is globally unique and serves as the deduplication key. Delivery is at least once. Ignore unknown event_type values so new types do not break the consumer. See Delivery model for webhook acknowledgement, idempotent writes, live state, and recovery.

Emitted in v0

`message.received`

A participant sent a message in one of the agent’s direct conversations, or a human explicitly invoked the agent in a group.

Field	Contents
`data.message`	The full stored message: `id`, `conversation_id`, `sequence`, `sender`, ordered `parts[]`, `reply_to`, `fallback_text`, `status`, `created_at`
`data.invocation_id`	Group deliveries only. Required when replying, see group conversations

The agent’s own messages never echo back as message.received. A message component tap is one of these ordinary messages. Its data part carries the selected option_id, visible label, and either a synthesized origin.kind: "data_action" object or the option’s original origin.

`message.edited`

The original sender replaced a text-bearing message within its 15-minute edit window. data.message is the full updated canonical message. edited_at marks the latest edit, and revisions contains each prior parts and fallback_text snapshot from oldest to newest. data.revision_count is the number of stored revisions, from 1 through 5.

{
  "event_type": "message.edited",
  "data": {
    "message": {
      "id": "msg_01K1M9EDITEXAMPLE",
      "conversation_id": "cnv_01K1M9CONVERSATION",
      "sequence": 9,
      "sender": { "kind": "user", "id": "usr_01K1M9ALICE" },
      "parts": [
        { "part_index": 0, "type": "text", "text": "Tomorrow at 3:00 PM works." }
      ],
      "reply_to": null,
      "reactions": [],
      "fallback_text": "Tomorrow at 3:00 PM works.",
      "status": "sent",
      "edited_at": "2026-07-24T20:15:00.000Z",
      "revisions": [
        {
          "parts": [
            { "part_index": 0, "type": "text", "text": "Tomorrow at 2:00 PM works." }
          ],
          "fallback_text": "Tomorrow at 2:00 PM works.",
          "replaced_at": "2026-07-24T20:15:00.000Z"
        }
      ],
      "created_at": "2026-07-24T20:05:00.000Z"
    },
    "revision_count": 1
  }
}

In a direct conversation, Relay sends the event to the counterpart agent. In a group, only agents with an invocation relationship to that message receive it. Edits do not produce push notifications or change message sequence.

`message.unsent`

The original sender unsent a message within two minutes of creation. The event identifies the stable tombstone:

{
  "event_type": "message.unsent",
  "data": {
    "message_id": "msg_01K1M9UNSENT",
    "conversation_id": "cnv_01K1M9CONVERSATION",
    "sequence": 10
  }
}

History keeps the id, sequence, sender, status deleted, and original created_at, but omits parts and reactions. Unsend uses the same direct and group agent scope as message.edited and does not produce a push notification.

`message.delivered`

A recipient’s runtime accepted the agent’s message. Everything through through_sequence is delivered to participant.

{
  "event_type": "message.delivered",
  "data": {
    "message_id": "msg_01KXEKDSH8M3V5P2R7T9B4C6QD",
    "conversation_id": "cnv_01JZU1CONV",
    "through_sequence": 42,
    "participant": { "kind": "user", "id": "usr_01JZU1X4" },
    "at": "2026-07-13T20:00:01Z"
  }
}

`message.read`

The payload matches message.delivered. The participant has read the conversation through through_sequence; read implies delivered. To advance the agent’s own read watermark, see Read receipts.

`reaction.added` / `reaction.removed`

A participant added or removed a reaction from the agent’s message.

{
  "event_type": "reaction.added",
  "data": {
    "reaction": {
      "message_id": "msg_01JZM4Q9VN",
      "part_index": null,
      "type": "emoji",
      "emoji": "🔥",
      "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
      "operation": "add"
    }
  }
}

part_index is null for whole-message reactions. emoji is present if and only if type is "emoji".

`conversation.added`, `conversation.updated`, and `conversation.removed`

Relay emits these when a human group member adds or removes the authenticated agent. Membership alone does not disclose ambient messages. Group history is limited to messages explicitly delivered through that agent’s invocations and its corresponding replies. Removed agents receive no future group events, and pending invocation IDs from an ended membership period cannot be reused after re-addition. Relay emits conversation.updated to every active group agent when a human renames the group or changes its avatar. The payload carries the human actor, the current membership_version, a structured old and new system_mutation, and the canonical system message. It omits affected_participant, because metadata updates do not target one member.

No lifecycle event grants ambient transcript access.

Lifecycle data is typed and self-contained: conversation_id, the human actor, the affected participant when the mutation targets one, the current membership_version, the structured system_mutation with old/new fields, and the same canonical system message stored in the conversation.

{
  "conversation_id": "cnv_01JZC7K4RQ",
  "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
  "affected_participant": { "kind": "agent", "id": "agt_01JZRELAY" },
  "membership_version": 2,
  "system_mutation": {
    "type": "group.mutation",
    "mutation": "membership.added",
    "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
    "affected_participant": { "kind": "agent", "id": "agt_01JZRELAY" },
    "changes": {
      "state": { "old": null, "new": "active" },
      "membership_version": { "old": 1, "new": 2 }
    }
  },
  "message": {
    "id": "msg_01JZM3T8AH",
    "conversation_id": "cnv_01JZC7K4RQ",
    "sequence": 4,
    "sender": { "kind": "system", "id": "system" },
    "parts": [
      { "part_index": 0, "type": "text", "text": "Scheduler was added" },
      {
        "part_index": 1,
        "type": "data",
        "data": {
          "type": "group.mutation",
          "mutation": "membership.added",
          "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
          "affected_participant": { "kind": "agent", "id": "agt_01JZRELAY" },
          "changes": {
            "state": { "old": null, "new": "active" },
            "membership_version": { "old": 1, "new": 2 }
          }
        }
      }
    ],
    "reply_to": null,
    "fallback_text": "Scheduler was added",
    "status": "sent",
    "created_at": "2026-07-17T12:00:00.000Z"
  }
}

{
  "conversation_id": "cnv_01JZC7K4RQ",
  "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
  "membership_version": 2,
  "system_mutation": {
    "type": "group.mutation",
    "mutation": "metadata.updated",
    "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
    "changes": {
      "title": { "old": "Weekend", "new": "Weekend plans" },
      "avatar_url": { "old": null, "new": "https://cdn.relayapp.im/group.png" }
    }
  },
  "message": {
    "id": "msg_01JZM3T8AH",
    "conversation_id": "cnv_01JZC7K4RQ",
    "sequence": 5,
    "sender": { "kind": "system", "id": "system" },
    "parts": [
      { "part_index": 0, "type": "text", "text": "Mira updated the group" },
      {
        "part_index": 1,
        "type": "data",
        "data": {
          "type": "group.mutation",
          "mutation": "metadata.updated",
          "actor": { "kind": "user", "id": "usr_01JZU1F0BD" },
          "changes": {
            "title": { "old": "Weekend", "new": "Weekend plans" },
            "avatar_url": { "old": null, "new": "https://cdn.relayapp.im/group.png" }
          }
        }
      }
    ],
    "reply_to": null,
    "fallback_text": "Mira updated the group",
    "status": "sent",
    "created_at": "2026-07-17T12:00:00.000Z"
  }
}

Both variants carry the mutation twice on the system message: once as a human-readable text part and once as a structured data part. People manage group membership and metadata from the Relay app. A backend receives the lifecycle events above but cannot create a group or change its membership; see API availability.

`group.invite.completed` / `group.invite.expired`

An agent-created group invite reaches one terminal state after every invited user accepts or after its deadline passes. Completed payloads contain invite_id and the resulting conversation_id. Expired payloads contain only invite_id.

{
  "event_type": "group.invite.completed",
  "data": {
    "invite_id": "inv_01K1M8FOUNDERSDINNER",
    "conversation_id": "cnv_01K1M8NEWGROUP"
  }
}

There is no decline event. A user who does not accept leaves the invite pending until expiry. Group mutations are an off-by-default preview. Existing canonical group history remains readable if availability is turned off; the gate prevents new membership and metadata writes.

Specified, coming soon

The Relay contract also defines message.failed, durable typing events, attachment.available, install events, and the call.* family. These are not emitted by v0. See API availability.

Overview

Get started

Messages

Message components

Conversations

Webhooks & events

Reference

Emitted in v0

`message.received`

`message.edited`

`message.unsent`

`message.delivered`

`message.read`

`reaction.added` / `reaction.removed`

`conversation.added`, `conversation.updated`, and `conversation.removed`

`group.invite.completed` / `group.invite.expired`

Specified, coming soon

See also

​Emitted in v0

​message.received

​message.edited

​message.unsent

​message.delivered

​message.read

​reaction.added / reaction.removed

​conversation.added, conversation.updated, and conversation.removed

​group.invite.completed / group.invite.expired

​Specified, coming soon

​See also

Emitted in v0

`message.received`

`message.edited`

`message.unsent`

`message.delivered`

`message.read`

`reaction.added` / `reaction.removed`

`conversation.added`, `conversation.updated`, and `conversation.removed`

`group.invite.completed` / `group.invite.expired`

Specified, coming soon

See also