Conversations

Manage chat conversations backed by Matrix (Synapse). sphere-chat orchestrates Matrix rooms and provides a unified API for creating, updating, and managing conversations and their members. Matrix is the source of truth for messages; sphere-chat handles room lifecycle and membership.

The conversation model

Conversations map to Matrix rooms. Each conversation has a type that determines its behavior and visibility.

Properties

Name
id
Type
string
Description
Unique UUID identifier for the conversation.
Name
matrix_room_id
Type
string
Description
The underlying Matrix room ID (e.g., !abc123:your-sphere.example.com).
Name
name
Type
string
Description
Display name of the conversation. For direct conversations, this is typically derived from the other participant's name.
Name
type
Type
string
Description
The conversation type. One of direct, group, or channel.
Name
avatar_url
Type
string | null
Description
URL to the conversation avatar image, or null if none is set.
Name
members_count
Type
integer
Description
Number of members currently in the conversation.
Name
created_at
Type
timestamp
Description
ISO 8601 timestamp of when the conversation was created.

GET/chat/api/v1/conversations

List conversations

Retrieve a paginated list of conversations the authenticated user is a member of. Results include direct messages, group conversations, and channels.

Optional attributes

Name
type
Type
string
Description
Filter by conversation type: direct, group, or channel.
Name
cursor
Type
string
Description
Cursor for pagination. Use the value from the previous response to fetch the next page.
Name
limit
Type
integer
Description
Number of conversations to return per page. Default is 50.

Request

GET

/chat/api/v1/conversations

curl -G https://your-sphere.example.com/chat/api/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -d type=group \
  -d limit=20

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "matrix_room_id": "!roomABC123:your-sphere.example.com",
      "name": "Engineering Team",
      "type": "group",
      "avatar_url": "https://your-sphere.example.com/chat/avatars/eng-team.png",
      "members_count": 12,
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "matrix_room_id": "!roomDEF456:your-sphere.example.com",
      "name": "Product Updates",
      "type": "channel",
      "avatar_url": null,
      "members_count": 45,
      "created_at": "2026-01-10T08:00:00Z"
    }
  ]
}

POST/chat/api/v1/conversations

Create conversation

Create a new conversation. This provisions a Matrix room behind the scenes and invites the specified members. For direct conversations, provide exactly one member ID. For group and channel types, provide a name and one or more member IDs.

Required attributes

Name
type
Type
string
Description
The conversation type: direct, group, or channel.
Name
member_ids
Type
array
Description
Array of user UUIDs to invite to the conversation. For direct type, provide exactly one UUID.

Optional attributes

Name
name
Type
string
Description
Display name for the conversation. Required for group and channel types. Ignored for direct conversations.

Request

POST

/chat/api/v1/conversations

curl -X POST https://your-sphere.example.com/chat/api/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Alpha",
    "type": "group",
    "member_ids": [
      "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "d4e5f6a7-b8c9-0123-defa-234567890123"
    ]
  }'

Response

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "matrix_room_id": "!newRoom789:your-sphere.example.com",
    "name": "Project Alpha",
    "type": "group",
    "avatar_url": null,
    "members_count": 3,
    "created_at": "2026-02-24T14:00:00Z"
  }
}

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

Get conversation

Retrieve the details of a specific conversation by its UUID. The authenticated user must be a member of the conversation.

URL parameters

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

Request

GET

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

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

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "matrix_room_id": "!roomABC123:your-sphere.example.com",
    "name": "Engineering Team",
    "type": "group",
    "avatar_url": "https://your-sphere.example.com/chat/avatars/eng-team.png",
    "members_count": 12,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

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

Update conversation

Update the display name or avatar of an existing conversation. Only group and channel conversations can be updated. Changes are propagated to the underlying Matrix room.

URL parameters

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

Optional attributes

Name
name
Type
string
Description
New display name for the conversation.
Name
avatar_url
Type
string
Description
New avatar URL for the conversation.

Request

PATCH

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

curl -X PATCH https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team v2",
    "avatar_url": "https://your-sphere.example.com/chat/avatars/eng-v2.png"
  }'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "matrix_room_id": "!roomABC123:your-sphere.example.com",
    "name": "Engineering Team v2",
    "type": "group",
    "avatar_url": "https://your-sphere.example.com/chat/avatars/eng-v2.png",
    "members_count": 12,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

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

Add member

Add a user to an existing conversation. The user is invited to the underlying Matrix room. Only group and channel conversations support adding members.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.

Required attributes

Name
user_id
Type
string
Description
The UUID of the user to add to the conversation.

Request

POST

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

curl -X POST https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "f6a7b8c9-d0e1-2345-fabC-456789012345"
  }'

Response (200)

{
  "message": "Member added successfully."
}

DELETE/chat/api/v1/conversations/{id}/members/{userId}

Remove member

Remove a user from a conversation. The user is kicked from the underlying Matrix room. Only group and channel conversations support removing members.

URL parameters

Name
id
Type
string
Description
The UUID of the conversation.
Name
userId
Type
string
Description
The UUID of the user to remove from the conversation.

Request

DELETE

/chat/api/v1/conversations/{id}/members/{userId}

curl -X DELETE https://your-sphere.example.com/chat/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members/f6a7b8c9-d0e1-2345-fabC-456789012345 \
  -H "Authorization: Bearer {token}"

Response (200)

{
  "message": "Member removed successfully."
}

GET/chat/api/v1/matrix/auth

Get Matrix auth

Retrieve a Matrix login token for the authenticated user. This allows direct access to the Matrix homeserver using a native Matrix client (e.g., Element). The login token is short-lived and single-use.

Use this endpoint when your application needs to connect directly to Matrix for features not covered by the sphere-chat API (e.g., end-to-end encryption key management, direct Matrix SDK usage).

Request

GET

/chat/api/v1/matrix/auth

curl https://your-sphere.example.com/chat/api/v1/matrix/auth \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "login_token": "syt_bWF0cml4X2xvZ2luX3Rva2Vu...",
    "homeserver_url": "https://matrix.your-sphere.example.com",
    "user_id": "@user_a1b2c3:your-sphere.example.com"
  }
}