Event types

Every delivered event uses Linq’s current v3 webhook envelope.

{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "evt_01m135vfepewek1yqy3p82yszs",
  "created_at": "2026-08-27T18:06:02.000Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "agt_01jz9x4t2snbqe6m8v3kcyh7wd",
  "data": {}
}

Field	Contents
`api_version`	`v3`
`webhook_version`	`2026-02-03`
`event_type`	Linq event name
`event_id`	Stable deduplication key, also sent as `webhook-id`
`created_at`	Event creation time
`trace_id`	Debugging correlation ID
`partner_id`	Receiving agent ID
`data`	Event-specific Linq payload

Relay’s prefixed IDs remain the values because Relay owns those identities. The field names, nesting, and event names follow Linq.

Supported events

Event	Fires when
`message.sent`	An outbound message was committed
`message.received`	An inbound message arrived
`message.delivered`	An outbound message reached its recipient
`message.read`	An outbound message was read
`reaction.added` / `reaction.removed`	A reaction was added or removed
`chat.created`	A conversation was created
`chat.group_name_updated` / `chat.group_icon_updated`	Group metadata changed
`participant.added` / `participant.removed`	Group membership changed

Message events

message.sent, message.received, message.delivered, and message.read share Linq’s MessageEventV2 data shape.

Field	Contents
`chat`	`{ id, is_group, owner_handle, health_status }`
`id`	Message ID
`direction`	`inbound` or `outbound`
`sender_handle`	Linq `ChatHandle` object
`parts`	Ordered Linq text, media, or link parts
`effect`	Message effect or `null`
`reply_to`	`{ message_id, part_index? }` or `null`
`sent_at`	Message send time
`delivered_at`	Delivery time at the delivered/read stage, otherwise `null`
`read_at`	Read time at the read stage, otherwise `null`
`service`	`iMessage`
`idempotency_key`	Outbound only, currently `null`
`preferred_service`	Outbound only, currently `null`

{
  "chat": {
    "id": "cnv_01jz9x4t3af8rjq2w6y5nkd0vh",
    "is_group": false,
    "owner_handle": {
      "id": "agt_01jz9x4t2snbqe6m8v3kcyh7wd",
      "handle": "relay",
      "is_me": true,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-08-27T18:00:00.000Z",
      "left_at": null
    },
    "health_status": {
      "status": "HEALTHY",
      "doc_url": "https://docs.linqapp.com/guides/chats/chat-health#healthy",
      "updated_at": "2026-08-27T18:06:02.000Z"
    }
  },
  "id": "msg_01jz9xa2tqe8vh5k2wy7ncd4rb",
  "direction": "inbound",
  "sender_handle": {
    "id": "usr_01jz8w2k5qnd7vh3e9tcyf4mrb",
    "handle": "morrison",
    "is_me": false,
    "service": "iMessage",
    "status": "active",
    "joined_at": "2026-08-27T18:00:00.000Z",
    "left_at": null
  },
  "parts": [{ "type": "text", "value": "Move standup to 10" }],
  "effect": null,
  "reply_to": null,
  "sent_at": "2026-08-27T18:06:02.000Z",
  "delivered_at": null,
  "read_at": null,
  "service": "iMessage"
}

Parts

{ "type": "text", "value": "Hello" }

{
  "id": "att_01jz9xb72qfd4mv6kc0w3re8tn",
  "filename": "photo.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 245678,
  "type": "media",
  "url": "https://api.relayapp.im/v1/attachments/att_01jz9xb72qfd4mv6kc0w3re8tn"
}

{ "type": "link", "value": "https://example.com" }

Reaction events

reaction.added and reaction.removed use Linq’s reaction shape. Removal creates its own event with reacted_at set to the removal time.

{
  "chat_id": "cnv_01jz9x4t3af8rjq2w6y5nkd0vh",
  "message_id": "msg_01jz9xa2tqe8vh5k2wy7ncd4rb",
  "part_index": 0,
  "reaction_type": "custom",
  "custom_emoji": "🔥",
  "is_from_me": false,
  "from": "morrison",
  "from_handle": {
    "id": "usr_01jz8w2k5qnd7vh3e9tcyf4mrb",
    "handle": "morrison",
    "is_me": false,
    "service": "iMessage",
    "status": "active",
    "joined_at": "2026-08-27T18:00:00.000Z",
    "left_at": null
  },
  "service": "iMessage",
  "reacted_at": "2026-08-27T18:08:00.000Z",
  "sticker": null
}

reaction_type is one of love, like, dislike, laugh, emphasize, question, or custom. custom_emoji contains the emoji only for custom.

Chat and participant events

chat.created carries the Linq chat object:

Field	Contents
`id`	Chat ID
`display_name`	Current display name
`service`	`iMessage`
`handles`	Current Linq `ChatHandle` roster
`is_group`	Group discriminator
`created_at` / `updated_at`	Chat timestamps
`health_status`	Linq health object

Group name and icon events carry chat_id, old_value, new_value, changed_by_handle, and updated_at. Participant events carry chat_id, handle, and the full participant handle. participant.added adds added_at; participant.removed adds removed_at and reports the participant with status: "removed".

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Supported events

Message events

Parts

Reaction events

Chat and participant events

See also

​Supported events

​Message events

​Parts

​Reaction events

​Chat and participant events

​See also

Supported events

Message events

Parts

Reaction events

Chat and participant events

See also