Append a message event

Operation boundary

Caller: Trusted backend only
Scope: Requires a committed persistent stream base with matching identity. Public events are delivered best effort to online Sessions; private/restricted events are not broadcast. Ordinary message sync does not enforce visibility access control; a trusted backend must authorize and filter.
Success: Success confirms projection acceptance, not online display. Complete terminal snapshots and offline message sync provide recovery. Retry an uncertain write with the exact same event_id and payload.

POST/message/event

Validates and applies one message-scoped event projection; non-null headers are unsupported.

Request Body

application/json

Event to project onto one message.

TypeScript Definitions

Use the request body type in TypeScript.

Message-event projection parameters.

channel_id*string

Target non-blank Channel ID; person and Agent Channels are normalized by the use case.

Match\S

Length1 <= length

channel_type*integer

Numeric Channel type; 1 is a person Channel, 2 is a group Channel, and other values are extension types.

Formatuint8

Range1 <= value <= 255

from_uid?string

Event actor UID; a non-empty value must match the committed base sender. Person or unencoded Agent Channel normalization may require it.

message_id?integer

Optional server message ID; a positive value must match the committed base, while 0 or negative values are omitted from the event command.

Formatint64

client_msg_no*string

Non-blank client message number of the message receiving the event.

Match\S

Length1 <= length

event_id*string

Non-blank unique identifier of this event.

Match\S

Length1 <= length

event_type*string

Event type; surrounding whitespace is removed and the value is lowercased.

Match

^\s*[sS][tT][rR][eE][aA][mM]\.(?:[oO][pP][eE][nN]|[dD][eE][lL][tT][aA]|[cC][lL][oO][sS][eE]|[eE][rR][rR][oO][rR]|[cC][aA][nN][cC][eE][lL]|[sS][nN][aA][pP][sS][hH][oO][tT]|[fF][iI][nN][iI][sS][hH])\s*$

Length1 <= length

event_key?string

Event lane key; empty selects the default lane and stream.finish forces the finish lane.

visibility?string

Caller-supplied event metadata stored after normalization; empty defaults to public, and only public events are broadcast online. Ordinary message sync does not filter by it; eventsync filters by include_private without checking caller permissions.

occurred_at?integer

Caller-supplied integer event time; the entry does not interpret its unit.

Formatint64

payload?unknown

Arbitrary JSON event payload passed to event storage as raw JSON bytes.

headers?null

Deprecated

Reserved field; it must be omitted or null, and every non-null JSON value is rejected.

[key: string]?any

Response Body

`application/json`

{  "status": 200,  "data": {    "client_msg_no": "string",    "event_key": "string",    "event_id": "string",    "msg_event_seq": 0,    "stream_status": "open",    "channel_id": "string",    "channel_type": 0,    "from_uid": "string"  }}

Append a message event

Request Body

Response Body

200application/json

400application/json

503application/json

`application/json`

`application/json`

`application/json`