Real-Time Signals

Real-time signals power the live aspects of chat: presence indicators, typing notifications, read receipts, and event streams. sphere-chat provides both a Server-Sent Events (SSE) stream for continuous updates and individual endpoints for querying and sending specific signals.

The SSE stream is the recommended way to receive real-time updates. It consolidates all signal types (presence, typing, receipts, messages, notifications) into a single connection, reducing overhead compared to polling individual endpoints.

GET/chat/api/v1/conversations/{id}/signals

SSE event stream

Open a Server-Sent Events (SSE) connection for a specific conversation. The stream delivers real-time events as they occur, including new messages, typing indicators, presence changes, read receipts, and notifications.

The connection remains open until the client disconnects. Implement automatic reconnection with the Last-Event-ID header to resume from where you left off.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation to subscribe to.

Event types

Name
presence
Description
A user's online status changed (online, offline, unavailable).
Name
typing
Description
A user started or stopped typing.
Name
receipt
Description
A user read a message (read receipt).
Name
message
Description
A new message was sent in the conversation.
Name
notification
Description
A notification was generated (mention, unread).

Request

GET

/chat/api/v1/conversations/{id}/signals

curl -N https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/signals \
  -H "Authorization: Bearer {token}" \
  -H "Accept: text/event-stream"

SSE Stream

event: typing
data: {"user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "typing": true}

event: message
data: {"id": "msg-abc123", "sender_user_id": "c3d4e5f6-...", "preview": "Hello!"}

event: presence
data: {"user_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "status": "online"}

event: receipt
data: {"user_id": "c3d4e5f6-...", "event_id": "$evt_abc123:..."}

GET/chat/api/v1/conversations/{id}/signals/snapshot

Get state snapshot

Retrieve the current state snapshot for a conversation. This returns the latest presence, typing status, and read receipt state for all members. Use this to initialize your UI before subscribing to the SSE stream.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Request

GET

/chat/api/v1/conversations/{id}/signals/snapshot

curl https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/signals/snapshot \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "presence": [
      {"user_id": "c3d4e5f6-...", "status": "online", "last_active_at": "2026-02-24T14:35:00Z"},
      {"user_id": "d4e5f6a7-...", "status": "offline", "last_active_at": "2026-02-24T12:00:00Z"}
    ],
    "typing": [],
    "receipts": [
      {"user_id": "c3d4e5f6-...", "last_read_event_id": "$evt_abc123:..."}
    ]
  }
}

POST/chat/api/v1/conversations/{id}/typing

Send typing indicator

Notify other members that the authenticated user is typing (or has stopped typing) in a conversation. Typing indicators automatically expire after a short timeout if not refreshed.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Required attributes

Name
typing
Type
boolean
Description
true when the user starts typing, false when they stop.

Request

POST

/chat/api/v1/conversations/{id}/typing

curl -X POST https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/typing \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"typing": true}'

Response (200)

{
  "message": "Typing indicator sent."
}

GET/chat/api/v1/conversations/{id}/typing

Get typing users

Retrieve the list of users currently typing in a conversation. This is a point-in-time query; for continuous updates, use the SSE stream instead.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Request

GET

/chat/api/v1/conversations/{id}/typing

curl https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/typing \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "started_at": "2026-02-24T14:35:12Z"
    }
  ]
}

GET/chat/api/v1/presence/{userId}

Get user presence

Retrieve the current presence status of a specific user. Presence statuses are online, offline, or unavailable.

URL parameters

Name
userId
Type
string
Description
The UUID of the user whose presence to query.

Request

GET

/chat/api/v1/presence/{userId}

curl https://your-sphere.example.com/chat/api/v1/presence/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "status": "online",
    "last_active_at": "2026-02-24T14:35:00Z"
  }
}

PUT/chat/api/v1/presence

Set own presence

Set the authenticated user's presence status. This broadcasts the change to all conversations the user is a member of.

Required attributes

Name
status
Type
string
Description
The presence status to set. One of online, offline, or unavailable.

Request

PUT

/chat/api/v1/presence

curl -X PUT https://your-sphere.example.com/chat/api/v1/presence \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

Response (200)

{
  "data": {
    "user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "status": "online",
    "last_active_at": "2026-02-24T14:36:00Z"
  }
}

POST/chat/api/v1/conversations/{id}/read

Send read receipt

Send a read receipt for a specific Matrix event in a conversation. This marks the message (and all preceding messages) as read for the authenticated user.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Required attributes

Name
event_id
Type
string
Description
The Matrix event ID to mark as read (e.g., $evt_abc123:your-sphere.example.com).

Request

POST

/chat/api/v1/conversations/{id}/read

curl -X POST https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/read \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "$evt_abc123:your-sphere.example.com"}'

Response (200)

{
  "message": "Read receipt sent."
}

GET/chat/api/v1/conversations/{id}/receipts

Get read receipts

Retrieve the latest read receipts for all members of a conversation. Each entry shows the last Matrix event each user has read.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Request

GET

/chat/api/v1/conversations/{id}/receipts

curl https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/receipts \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "last_read_event_id": "$evt_abc123:your-sphere.example.com",
      "read_at": "2026-02-24T14:35:30Z"
    },
    {
      "user_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "last_read_event_id": "$evt_def456:your-sphere.example.com",
      "read_at": "2026-02-24T14:30:00Z"
    }
  ]
}

POST/chat/api/v1/conversations/{id}/marker

Set read marker

Set the read marker position for a conversation. The read marker represents the point up to which the user has scrolled and seen messages. Unlike read receipts (which track individual message reads), the read marker tracks the scroll position in the conversation timeline.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Required attributes

Name
event_id
Type
string
Description
The Matrix event ID to set as the read marker position.

Request

POST

/chat/api/v1/conversations/{id}/marker

curl -X POST https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/marker \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "$evt_abc123:your-sphere.example.com"}'

Response (200)

{
  "message": "Read marker set."
}