Chat Inbox

The inbox is the primary view for a user's chat conversations, ordered by priority: pinned conversations first, then unread conversations, then by most recent activity. It provides a unified interface for managing conversation state (pin, mute, read) and searching across all conversations.

The inbox item model

Each inbox item represents a conversation from the user's perspective, enriched with unread counts, last message preview, and user preferences.

Properties

Name
conversation_id
Type
string
Description
UUID of the conversation.
Name
name
Type
string
Description
Display name of the conversation.
Name
type
Type
string
Description
Conversation type: direct, group, or channel.
Name
last_message_preview
Type
string | null
Description
Plaintext preview of the last message. null if the conversation has no messages or the last message is encrypted.
Name
last_message_at
Type
timestamp | null
Description
ISO 8601 timestamp of the last message in the conversation.
Name
unread_count
Type
integer
Description
Number of unread messages in the conversation for the authenticated user.
Name
is_pinned
Type
boolean
Description
Whether the conversation is pinned to the top of the inbox.
Name
is_muted
Type
boolean
Description
Whether notifications are muted for this conversation.
Name
avatar_url
Type
string | null
Description
URL to the conversation avatar image.
Name
last_message
Type
object | null
Description
Summary of the last message, including sender_name.

GET/chat/api/v1/inbox

List inbox

Retrieve the authenticated user's chat inbox. Conversations are ordered by priority: pinned first, then unread, then by most recent activity. Supports cursor-based pagination and text search.

Optional attributes

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 inbox items to return per page. Default is 50.
Name
search
Type
string
Description
Filter conversations by name or last message content.

Request

GET

/chat/api/v1/inbox

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

Response

{
  "data": [
    {
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Engineering Team",
      "type": "group",
      "last_message_preview": "Deployment completed successfully.",
      "last_message_at": "2026-02-24T14:35:00Z",
      "unread_count": 3,
      "is_pinned": true,
      "is_muted": false,
      "avatar_url": "https://your-sphere.example.com/chat/avatars/eng-team.png",
      "last_message": {
        "sender_name": "Alice Martin"
      }
    },
    {
      "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Bob Johnson",
      "type": "direct",
      "last_message_preview": "Can you review the PR?",
      "last_message_at": "2026-02-24T14:20:00Z",
      "unread_count": 1,
      "is_pinned": false,
      "is_muted": false,
      "avatar_url": null,
      "last_message": {
        "sender_name": "Bob Johnson"
      }
    },
    {
      "conversation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "General",
      "type": "channel",
      "last_message_preview": "Welcome to the new quarter!",
      "last_message_at": "2026-02-24T09:00:00Z",
      "unread_count": 0,
      "is_pinned": false,
      "is_muted": true,
      "avatar_url": null,
      "last_message": {
        "sender_name": "Admin"
      }
    }
  ]
}

PATCH/chat/api/v1/inbox/{conversationId}

Update inbox item

Update the inbox state for a specific conversation. Use this to pin or unpin a conversation, or to mute or unmute notifications.

URL parameters

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

Optional attributes

Name
is_pinned
Type
boolean
Description
Set to true to pin the conversation to the top of the inbox, or false to unpin.
Name
is_muted
Type
boolean
Description
Set to true to mute notifications for the conversation, or false to unmute.

Request

PATCH

/chat/api/v1/inbox/{conversationId}

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

Response

{
  "data": {
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "is_pinned": true,
    "is_muted": false
  }
}

POST/chat/api/v1/inbox/{conversationId}/read

Mark conversation as read

Mark all messages in a conversation as read for the authenticated user. This resets the unread count to zero and updates the read receipt to the latest message.

URL parameters

Name
conversationId
Type
string
Description
The UUID of the conversation to mark as read.

Request

POST

/chat/api/v1/inbox/{conversationId}/read

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

Response (200)

{
  "message": "Conversation marked as read."
}

POST/chat/api/v1/inbox/bulk-read

Bulk mark as read

Mark multiple conversations as read in a single request. Provide an array of conversation UUIDs to reset their unread counts. Maximum 50 conversations per request.

Required attributes

Name
conversation_ids
Type
array
Description
Array of conversation UUIDs to mark as read. Maximum 50 items.

Request

POST

/chat/api/v1/inbox/bulk-read

curl -X POST https://your-sphere.example.com/chat/api/v1/inbox/bulk-read \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

Response (200)

{
  "message": "2 conversations marked as read."
}

GET/chat/api/v1/inbox/search

Search inbox

Search across all inbox conversations by name or message content. Returns matching conversations with highlighted context. Results are ranked by relevance.

Required attributes

Name
q
Type
string
Description
The search query string. Matches against conversation names and message content.

Optional attributes

Name
cursor
Type
string
Description
Cursor for pagination.
Name
limit
Type
integer
Description
Number of results to return per page. Default is 20.

Request

GET

/chat/api/v1/inbox/search

curl -G https://your-sphere.example.com/chat/api/v1/inbox/search \
  -H "Authorization: Bearer {token}" \
  -d q=deployment \
  -d limit=10

Response

{
  "data": [
    {
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Engineering Team",
      "type": "group",
      "last_message_preview": "Deployment completed successfully.",
      "last_message_at": "2026-02-24T14:35:00Z",
      "unread_count": 3,
      "is_pinned": true,
      "is_muted": false,
      "avatar_url": "https://your-sphere.example.com/chat/avatars/eng-team.png",
      "last_message": {
        "sender_name": "Alice Martin"
      }
    }
  ]
}