Event Stream

SSE Endpoint

Opens a persistent Server-Sent Events stream for real-time notifications.

GET /api/v1/events

Authentication: Required.

Response

• Content-Type: text/event-stream
• The connection remains open indefinitely.
• The server sends periodic keep-alive comments (: lines) to prevent timeouts.

Wire Format

Each event is sent as an SSE data: line containing a hex-encoded serialized ServerEvent protobuf message:

data: <hex-encoded protobuf bytes>\n\n

Protobuf Definition

message ServerEvent {
  oneof event {
    NewMessageEvent new_message = 1;
    GroupUpdateEvent group_update = 2;
    WelcomeEvent welcome = 3;
    MemberRemovedEvent member_removed = 4;
    IdentityResetEvent identity_reset = 5;
    InviteReceivedEvent invite_received = 6;
    InviteDeclinedEvent invite_declined = 7;
    InviteCancelledEvent invite_cancelled = 8;
    GroupDeletedEvent group_deleted = 9;
  }
}

Event Type Reference

NewMessageEvent

A new encrypted message was stored in a group.

message NewMessageEvent {
  int64 group_id = 1;
  uint64 sequence_num = 2;
  int64 sender_id = 3;
}

Recipients: All group members except the sender.

GroupUpdateEvent

Group state changed (member roster, metadata, or roles).

message GroupUpdateEvent {
  int64 group_id = 1;
  string update_type = 2;
}

WelcomeEvent

A pending Welcome message is ready for the user to process.

message WelcomeEvent {
  int64 group_id = 1;
  string group_alias = 2;
}

Recipients: The invitee only.

MemberRemovedEvent

A member was removed or left a group.

message MemberRemovedEvent {
  int64 group_id = 1;
  int64 removed_user_id = 2;
}

Recipients: All remaining group members AND the removed user.

IdentityResetEvent

A member rejoined a group with a new MLS identity via external commit.

message IdentityResetEvent {
  int64 group_id = 1;
  int64 user_id = 2;
}

Recipients: All group members except the user who reset.

InviteReceivedEvent

A pending invite was created for this user.

message InviteReceivedEvent {
  int64 invite_id = 1;
  int64 group_id = 2;
  string group_name = 3;
  string group_alias = 4;
  int64 inviter_id = 5;
}

Recipients: The invitee only.

InviteDeclinedEvent

An invitee declined a pending invite, or an admin cancelled an invite.

message InviteDeclinedEvent {
  int64 group_id = 1;
  int64 declined_user_id = 2;
}

Recipients: The original inviter only.

InviteCancelledEvent

An admin cancelled a pending invite for this user.

message InviteCancelledEvent {
  int64 group_id = 1;
}

Recipients: The invitee only.

GroupDeletedEvent

A group was permanently deleted by an admin.

message GroupDeletedEvent {
  int64 group_id = 1;
}

Recipients: All former group members (including the admin who deleted it).

Lag Handling

If a client’s SSE stream falls behind the server’s broadcast buffer, the server sends a transport-level notification:

event: lagged
data: <number of dropped events>

This is NOT a protobuf ServerEvent. It is a raw SSE event with the event type "lagged" and the data field containing the number of dropped events as a decimal string.

Clients SHOULD treat a lagged event as a signal to perform a full state refresh (re-fetch group lists, messages, and pending invites/welcomes).

Status Codes