API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Client

Top-level actions: focus Beeper Desktop, jump to a chat, or run unified search across chats and messages.

Focus Beeper Desktop app

focus(ClientFocusParams**kwargs) -> FocusResponse

POST/v1/focus

Search

search(ClientSearchParams**kwargs) -> SearchResponse

GET/v1/search

ModelsExpand Collapse

class FocusResponse: …

Response indicating successful app focus action.

success: bool

Whether the app was successfully opened/focused.

class SearchResponse: …

results: Results

chats: List[Chat]

Top chat results.

id: str

Unique identifier of the chat across Beeper.

account_id: str

Account ID this chat belongs to.

network: str

Display-only human-readable account/network name.

participants: Participants

Chat participants information.

has_more: bool

True if there are more participants than included in items.

items: List[ParticipantsItem]

Participants returned for this chat (limited by the request; may be a subset).

is_admin: Optional[bool]

True if this participant has admin privileges in the chat.

is_network_bot: Optional[bool]

True if this participant represents an automated network account.

is_pending: Optional[bool]

True if this participant has been invited but has not joined yet.

total: int

Total number of participants in the chat.

title: str

Display title of the chat as computed by the client/server.

type: Literal["single", "group"]

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

One of the following:

"single"

"group"

unread_count: int

Number of unread messages.

capabilities: Optional[Capabilities]

Chat capabilities reported by the platform.

allowed_reactions: Optional[List[str]]

Allowed Unicode reactions. Omitted means all emoji reactions are allowed.

archive: Optional[bool]

True if archive/unarchive is supported.

attachments: Optional[Dict[str, CapabilitiesAttachments]]

Supported attachment message types and their per-type constraints, keyed by Matrix msgtype or pseudo-msgtype (for example m.image, m.video, org.matrix.msc3245.voice). Missing message types should be treated as rejected.

mime_types: Dict[str, Literal[-2, -1, 0, 2 more]]

Supported MIME types or MIME patterns for this file message type. Missing MIME types should be treated as rejected.

One of the following:

-2

-1

0

1

2

caption: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

max_caption_length: Optional[int]

Maximum caption length when captions are supported.

max_duration: Optional[int]

Maximum audio or video duration in seconds.

max_height: Optional[int]

Maximum image or video height in pixels.

max_size: Optional[int]

Maximum file size in bytes.

max_width: Optional[int]

Maximum image or video width in pixels.

view_once: Optional[bool]

True if this file type can be sent as view-once media.

custom_emoji_reactions: Optional[bool]

True if custom emoji reactions are supported.

delete: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

delete_chat: Optional[bool]

True if deleting chats for the authenticated user is supported.

delete_chat_for_everyone: Optional[bool]

True if deleting chats for everyone is supported.

delete_for_me: Optional[bool]

True if deleting messages only for the authenticated user is supported.

delete_max_age: Optional[int]

Maximum message age for delete-for-everyone, in seconds.

disappearing_timer: Optional[CapabilitiesDisappearingTimer]

Disappearing-message timer capabilities.

omit_empty_timer: Optional[bool]

True if empty timer objects should be omitted from message content.

timers: Optional[List[int]]

Allowed disappearing timer values in milliseconds. Omitted means any timer is allowed.

types: Optional[List[Literal["afterRead", "afterSend"]]]

Supported disappearing timer types.

One of the following:

"afterRead"

"afterSend"

edit: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

edit_max_age: Optional[int]

Maximum message age for edits, in seconds.

edit_max_count: Optional[int]

Maximum number of edits allowed for one message.

formatting: Optional[Dict[str, Literal[-2, -1, 0, 2 more]]]

Supported rich-text formatting features keyed by feature name (for example bold, inline_code, code_block.syntax_highlighting). Omitted means no formatting support is advertised.

One of the following:

-2

-1

0

1

2

location_message: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

mark_as_unread: Optional[bool]

True if marking chats unread is supported.

max_text_length: Optional[int]

Maximum length of normal text messages.

message_request: Optional[CapabilitiesMessageRequest]

Message request capabilities.

accept_with_button: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

accept_with_message: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

participant_actions: Optional[CapabilitiesParticipantActions]

Participant management capabilities.

ban: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

invite: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

kick: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

leave: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

revoke_invite: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

poll: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

reaction: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

reaction_count: Optional[int]

Maximum number of reactions allowed on a single message.

read_receipts: Optional[bool]

True if read receipts are supported.

reply: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

state: Optional[CapabilitiesState]

Chat state update capabilities.

avatar: Optional[CapabilitiesStateAvatar]

Chat avatar state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

description: Optional[CapabilitiesStateDescription]

Chat description/topic state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

disappearing_timer: Optional[CapabilitiesStateDisappearingTimer]

Disappearing-message timer state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

title: Optional[CapabilitiesStateTitle]

Chat title state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

thread: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

typing_notifications: Optional[bool]

True if typing notifications are supported.

description: Optional[str]

Group chat description/topic when available.

draft: Optional[Draft]

Current draft object for this chat, or null when no draft is set.

text: str

Rich-text draft body as returned by Beeper.

attachments: Optional[Dict[str, DraftAttachments]]

Draft attachments keyed by attachment ID.

id: str

Draft attachment identifier.

type: Literal["file", "gif", "recorded_audio"]

Draft attachment type. GIF and recorded audio are mutually exclusive types.

One of the following:

"file"

"gif"

"recorded_audio"

audio_duration_seconds: Optional[float]

Audio duration in seconds if known.

file_name: Optional[str]

Original filename if available.

file_path: Optional[str]

Local filesystem path for the draft attachment.

file_size: Optional[float]

File size in bytes if known.

mime_type: Optional[str]

MIME type if known.

size: Optional[DraftAttachmentsSize]

Pixel dimensions of the attachment.

height: Optional[float]

width: Optional[float]

sticker_id: Optional[str]

Sticker identifier if the draft attachment is a sticker.

img_url: Optional[str]

Local filesystem path to the chat avatar image when available.

is_archived: Optional[bool]

True if chat is archived.

is_low_priority: Optional[bool]

True if chat is marked low priority.

is_marked_unread: Optional[bool]

True if the chat was explicitly marked unread by the authenticated user.

is_muted: Optional[bool]

True if chat notifications are muted.

is_pinned: Optional[bool]

True if chat is pinned.

is_read_only: Optional[bool]

True if messages cannot be sent in this chat.

last_activity: Optional[datetime]

Timestamp of last activity.

formatdate-time

last_read_message_sort_key: Optional[str]

Last read message sortKey.

local_chat_id: Optional[str]

Local chat ID specific to this installation.

message_expiry_seconds: Optional[int]

Disappearing-message timer in seconds when available.

reminder: Optional[Reminder]

Current reminder for this chat, or null when no reminder is set.

dismiss_on_incoming_message: Optional[bool]

Cancel reminder if someone messages in the chat.

remind_at: Optional[datetime]

Timestamp when the reminder should trigger.

formatdate-time

snooze: Optional[Snooze]

Current snooze state for this chat, or null when no snooze is set.

snooze_until: Optional[datetime]

Timestamp when the snooze expires.

formatdate-time

user_snoozed_at: Optional[datetime]

Timestamp when the user set the snooze.

formatdate-time

unread_mentions_count: Optional[int]

Number of unread messages that mention the authenticated user or @room.

in_groups: List[Chat]

Top group results by participant matches.

id: str

Unique identifier of the chat across Beeper.

account_id: str

Account ID this chat belongs to.

network: str

Display-only human-readable account/network name.

participants: Participants

Chat participants information.

has_more: bool

True if there are more participants than included in items.

items: List[ParticipantsItem]

Participants returned for this chat (limited by the request; may be a subset).

is_admin: Optional[bool]

True if this participant has admin privileges in the chat.

is_network_bot: Optional[bool]

True if this participant represents an automated network account.

is_pending: Optional[bool]

True if this participant has been invited but has not joined yet.

total: int

Total number of participants in the chat.

title: str

Display title of the chat as computed by the client/server.

type: Literal["single", "group"]

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

One of the following:

"single"

"group"

unread_count: int

Number of unread messages.

capabilities: Optional[Capabilities]

Chat capabilities reported by the platform.

allowed_reactions: Optional[List[str]]

Allowed Unicode reactions. Omitted means all emoji reactions are allowed.

archive: Optional[bool]

True if archive/unarchive is supported.

attachments: Optional[Dict[str, CapabilitiesAttachments]]

Supported attachment message types and their per-type constraints, keyed by Matrix msgtype or pseudo-msgtype (for example m.image, m.video, org.matrix.msc3245.voice). Missing message types should be treated as rejected.

mime_types: Dict[str, Literal[-2, -1, 0, 2 more]]

Supported MIME types or MIME patterns for this file message type. Missing MIME types should be treated as rejected.

One of the following:

-2

-1

0

1

2

caption: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

max_caption_length: Optional[int]

Maximum caption length when captions are supported.

max_duration: Optional[int]

Maximum audio or video duration in seconds.

max_height: Optional[int]

Maximum image or video height in pixels.

max_size: Optional[int]

Maximum file size in bytes.

max_width: Optional[int]

Maximum image or video width in pixels.

view_once: Optional[bool]

True if this file type can be sent as view-once media.

custom_emoji_reactions: Optional[bool]

True if custom emoji reactions are supported.

delete: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

delete_chat: Optional[bool]

True if deleting chats for the authenticated user is supported.

delete_chat_for_everyone: Optional[bool]

True if deleting chats for everyone is supported.

delete_for_me: Optional[bool]

True if deleting messages only for the authenticated user is supported.

delete_max_age: Optional[int]

Maximum message age for delete-for-everyone, in seconds.

disappearing_timer: Optional[CapabilitiesDisappearingTimer]

Disappearing-message timer capabilities.

omit_empty_timer: Optional[bool]

True if empty timer objects should be omitted from message content.

timers: Optional[List[int]]

Allowed disappearing timer values in milliseconds. Omitted means any timer is allowed.

types: Optional[List[Literal["afterRead", "afterSend"]]]

Supported disappearing timer types.

One of the following:

"afterRead"

"afterSend"

edit: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

edit_max_age: Optional[int]

Maximum message age for edits, in seconds.

edit_max_count: Optional[int]

Maximum number of edits allowed for one message.

formatting: Optional[Dict[str, Literal[-2, -1, 0, 2 more]]]

Supported rich-text formatting features keyed by feature name (for example bold, inline_code, code_block.syntax_highlighting). Omitted means no formatting support is advertised.

One of the following:

-2

-1

0

1

2

location_message: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

mark_as_unread: Optional[bool]

True if marking chats unread is supported.

max_text_length: Optional[int]

Maximum length of normal text messages.

message_request: Optional[CapabilitiesMessageRequest]

Message request capabilities.

accept_with_button: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

accept_with_message: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

participant_actions: Optional[CapabilitiesParticipantActions]

Participant management capabilities.

ban: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

invite: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

kick: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

leave: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

revoke_invite: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

poll: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

reaction: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

reaction_count: Optional[int]

Maximum number of reactions allowed on a single message.

read_receipts: Optional[bool]

True if read receipts are supported.

reply: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

state: Optional[CapabilitiesState]

Chat state update capabilities.

avatar: Optional[CapabilitiesStateAvatar]

Chat avatar state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

description: Optional[CapabilitiesStateDescription]

Chat description/topic state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

disappearing_timer: Optional[CapabilitiesStateDisappearingTimer]

Disappearing-message timer state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

title: Optional[CapabilitiesStateTitle]

Chat title state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

thread: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

typing_notifications: Optional[bool]

True if typing notifications are supported.

description: Optional[str]

Group chat description/topic when available.

draft: Optional[Draft]

Current draft object for this chat, or null when no draft is set.

text: str

Rich-text draft body as returned by Beeper.

attachments: Optional[Dict[str, DraftAttachments]]

Draft attachments keyed by attachment ID.

id: str

Draft attachment identifier.

type: Literal["file", "gif", "recorded_audio"]

Draft attachment type. GIF and recorded audio are mutually exclusive types.

One of the following:

"file"

"gif"

"recorded_audio"

audio_duration_seconds: Optional[float]

Audio duration in seconds if known.

file_name: Optional[str]

Original filename if available.

file_path: Optional[str]

Local filesystem path for the draft attachment.

file_size: Optional[float]

File size in bytes if known.

mime_type: Optional[str]

MIME type if known.

size: Optional[DraftAttachmentsSize]

Pixel dimensions of the attachment.

height: Optional[float]

width: Optional[float]

sticker_id: Optional[str]

Sticker identifier if the draft attachment is a sticker.

img_url: Optional[str]

Local filesystem path to the chat avatar image when available.

is_archived: Optional[bool]

True if chat is archived.

is_low_priority: Optional[bool]

True if chat is marked low priority.

is_marked_unread: Optional[bool]

True if the chat was explicitly marked unread by the authenticated user.

is_muted: Optional[bool]

True if chat notifications are muted.

is_pinned: Optional[bool]

True if chat is pinned.

is_read_only: Optional[bool]

True if messages cannot be sent in this chat.

last_activity: Optional[datetime]

Timestamp of last activity.

formatdate-time

last_read_message_sort_key: Optional[str]

Last read message sortKey.

local_chat_id: Optional[str]

Local chat ID specific to this installation.

message_expiry_seconds: Optional[int]

Disappearing-message timer in seconds when available.

reminder: Optional[Reminder]

Current reminder for this chat, or null when no reminder is set.

dismiss_on_incoming_message: Optional[bool]

Cancel reminder if someone messages in the chat.

remind_at: Optional[datetime]

Timestamp when the reminder should trigger.

formatdate-time

snooze: Optional[Snooze]

Current snooze state for this chat, or null when no snooze is set.

snooze_until: Optional[datetime]

Timestamp when the snooze expires.

formatdate-time

user_snoozed_at: Optional[datetime]

Timestamp when the user set the snooze.

formatdate-time

unread_mentions_count: Optional[int]

Number of unread messages that mention the authenticated user or @room.

messages: ResultsMessages

chats: Dict[str, Chat]

Map of chatID -> chat details for chats referenced in items.

id: str

Unique identifier of the chat across Beeper.

account_id: str

Account ID this chat belongs to.

network: str

Display-only human-readable account/network name.

participants: Participants

Chat participants information.

has_more: bool

True if there are more participants than included in items.

items: List[ParticipantsItem]

Participants returned for this chat (limited by the request; may be a subset).

is_admin: Optional[bool]

True if this participant has admin privileges in the chat.

is_network_bot: Optional[bool]

True if this participant represents an automated network account.

is_pending: Optional[bool]

True if this participant has been invited but has not joined yet.

total: int

Total number of participants in the chat.

title: str

Display title of the chat as computed by the client/server.

type: Literal["single", "group"]

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

One of the following:

"single"

"group"

unread_count: int

Number of unread messages.

capabilities: Optional[Capabilities]

Chat capabilities reported by the platform.

allowed_reactions: Optional[List[str]]

Allowed Unicode reactions. Omitted means all emoji reactions are allowed.

archive: Optional[bool]

True if archive/unarchive is supported.

attachments: Optional[Dict[str, CapabilitiesAttachments]]

Supported attachment message types and their per-type constraints, keyed by Matrix msgtype or pseudo-msgtype (for example m.image, m.video, org.matrix.msc3245.voice). Missing message types should be treated as rejected.

mime_types: Dict[str, Literal[-2, -1, 0, 2 more]]

Supported MIME types or MIME patterns for this file message type. Missing MIME types should be treated as rejected.

One of the following:

-2

-1

0

1

2

caption: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

max_caption_length: Optional[int]

Maximum caption length when captions are supported.

max_duration: Optional[int]

Maximum audio or video duration in seconds.

max_height: Optional[int]

Maximum image or video height in pixels.

max_size: Optional[int]

Maximum file size in bytes.

max_width: Optional[int]

Maximum image or video width in pixels.

view_once: Optional[bool]

True if this file type can be sent as view-once media.

custom_emoji_reactions: Optional[bool]

True if custom emoji reactions are supported.

delete: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

delete_chat: Optional[bool]

True if deleting chats for the authenticated user is supported.

delete_chat_for_everyone: Optional[bool]

True if deleting chats for everyone is supported.

delete_for_me: Optional[bool]

True if deleting messages only for the authenticated user is supported.

delete_max_age: Optional[int]

Maximum message age for delete-for-everyone, in seconds.

disappearing_timer: Optional[CapabilitiesDisappearingTimer]

Disappearing-message timer capabilities.

omit_empty_timer: Optional[bool]

True if empty timer objects should be omitted from message content.

timers: Optional[List[int]]

Allowed disappearing timer values in milliseconds. Omitted means any timer is allowed.

types: Optional[List[Literal["afterRead", "afterSend"]]]

Supported disappearing timer types.

One of the following:

"afterRead"

"afterSend"

edit: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

edit_max_age: Optional[int]

Maximum message age for edits, in seconds.

edit_max_count: Optional[int]

Maximum number of edits allowed for one message.

formatting: Optional[Dict[str, Literal[-2, -1, 0, 2 more]]]

Supported rich-text formatting features keyed by feature name (for example bold, inline_code, code_block.syntax_highlighting). Omitted means no formatting support is advertised.

One of the following:

-2

-1

0

1

2

location_message: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

mark_as_unread: Optional[bool]

True if marking chats unread is supported.

max_text_length: Optional[int]

Maximum length of normal text messages.

message_request: Optional[CapabilitiesMessageRequest]

Message request capabilities.

accept_with_button: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

accept_with_message: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

participant_actions: Optional[CapabilitiesParticipantActions]

Participant management capabilities.

ban: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

invite: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

kick: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

leave: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

revoke_invite: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

poll: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

reaction: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

reaction_count: Optional[int]

Maximum number of reactions allowed on a single message.

read_receipts: Optional[bool]

True if read receipts are supported.

reply: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

state: Optional[CapabilitiesState]

Chat state update capabilities.

avatar: Optional[CapabilitiesStateAvatar]

Chat avatar state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

description: Optional[CapabilitiesStateDescription]

Chat description/topic state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

disappearing_timer: Optional[CapabilitiesStateDisappearingTimer]

Disappearing-message timer state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

title: Optional[CapabilitiesStateTitle]

Chat title state capability.

level: Literal[-2, -1, 0, 2 more]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

thread: Optional[Literal[-2, -1, 0, 2 more]]

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

0

1

2

typing_notifications: Optional[bool]

True if typing notifications are supported.

description: Optional[str]

Group chat description/topic when available.

draft: Optional[Draft]

Current draft object for this chat, or null when no draft is set.

text: str

Rich-text draft body as returned by Beeper.

attachments: Optional[Dict[str, DraftAttachments]]

Draft attachments keyed by attachment ID.

id: str

Draft attachment identifier.

type: Literal["file", "gif", "recorded_audio"]

Draft attachment type. GIF and recorded audio are mutually exclusive types.

One of the following:

"file"

"gif"

"recorded_audio"

audio_duration_seconds: Optional[float]

Audio duration in seconds if known.

file_name: Optional[str]

Original filename if available.

file_path: Optional[str]

Local filesystem path for the draft attachment.

file_size: Optional[float]

File size in bytes if known.

mime_type: Optional[str]

MIME type if known.

size: Optional[DraftAttachmentsSize]

Pixel dimensions of the attachment.

height: Optional[float]

width: Optional[float]

sticker_id: Optional[str]

Sticker identifier if the draft attachment is a sticker.

img_url: Optional[str]

Local filesystem path to the chat avatar image when available.

is_archived: Optional[bool]

True if chat is archived.

is_low_priority: Optional[bool]

True if chat is marked low priority.

is_marked_unread: Optional[bool]

True if the chat was explicitly marked unread by the authenticated user.

is_muted: Optional[bool]

True if chat notifications are muted.

is_pinned: Optional[bool]

True if chat is pinned.

is_read_only: Optional[bool]

True if messages cannot be sent in this chat.

last_activity: Optional[datetime]

Timestamp of last activity.

formatdate-time

last_read_message_sort_key: Optional[str]

Last read message sortKey.

local_chat_id: Optional[str]

Local chat ID specific to this installation.

message_expiry_seconds: Optional[int]

Disappearing-message timer in seconds when available.

reminder: Optional[Reminder]

Current reminder for this chat, or null when no reminder is set.

dismiss_on_incoming_message: Optional[bool]

Cancel reminder if someone messages in the chat.

remind_at: Optional[datetime]

Timestamp when the reminder should trigger.

formatdate-time

snooze: Optional[Snooze]

Current snooze state for this chat, or null when no snooze is set.

snooze_until: Optional[datetime]

Timestamp when the snooze expires.

formatdate-time

user_snoozed_at: Optional[datetime]

Timestamp when the user set the snooze.

formatdate-time

unread_mentions_count: Optional[int]

Number of unread messages that mention the authenticated user or @room.

has_more: bool

True if additional results can be fetched using the provided cursors.

items: List[Message]

Messages matching the query and filters.

id: str

Message ID.

account_id: str

Beeper account ID the message belongs to.

chat_id: str

Chat ID. Input routes also accept the local chat ID from this installation when available.

sender_id: str

Fully qualified sender user ID. Network-backed IDs usually include the network prefix and homeserver.

sort_key: str

A unique, sortable key used to sort messages.

timestamp: datetime

Message timestamp.

formatdate-time

attachments: Optional[List[Attachment]]

Attachments included with this message, if any.

type: Literal["unknown", "img", "video", "audio"]

Attachment type.

One of the following:

"unknown"

"img"

"video"

"audio"

id: Optional[str]

Attachment identifier, typically an mxc:// URL. Use the download file endpoint to get a local file path.

duration: Optional[float]

Duration in seconds (audio/video).

file_name: Optional[str]

Original filename if available.

file_size: Optional[float]

File size in bytes if known.

is_gif: Optional[bool]

True if the attachment is a GIF.

is_sticker: Optional[bool]

True if the attachment is a sticker.

is_voice_note: Optional[bool]

True if the attachment is a voice note.

mime_type: Optional[str]

MIME type if known (e.g., ‘image/png’).

poster_img: Optional[str]

Preview image URL for video attachments (poster frame). May be temporary or available only on this device; download promptly if durable access is needed.

size: Optional[Size]

Pixel dimensions of the attachment: width/height in px.

height: Optional[float]

width: Optional[float]

src_url: Optional[str]

Public URL or local file path to fetch the file. May be temporary or available only on this device; download promptly if durable access is needed.

transcription: Optional[Transcription]

Attachment transcription if available.

engine: str

Transcription engine.

transcription: str

Transcribed text.

language: Optional[str]

Detected or selected language.

edited_timestamp: Optional[datetime]

Timestamp when the message was edited, if known.

formatdate-time

is_deleted: Optional[bool]

True if the message has been deleted.

is_hidden: Optional[bool]

True if the message is hidden from normal display.

is_sender: Optional[bool]

True if the authenticated user sent the message.

is_unread: Optional[bool]

True if the message is unread for the authenticated user. May be omitted.

linked_message_id: Optional[str]

ID of the message this is a reply to, if any.

links: Optional[List[Link]]

Link previews included with this message, if any.

title: str

Link preview title.

url: str

Resolved link URL.

favicon: Optional[str]

Favicon URL if available. May be temporary or available only on this device; download promptly if durable access is needed.

img: Optional[str]

Preview image URL if available. May be temporary or available only on this device; download promptly if durable access is needed.

img_size: Optional[LinkImgSize]

Preview image dimensions.

height: Optional[float]

width: Optional[float]

original_url: Optional[str]

Original URL when the displayed URL is shortened or redirected.

summary: Optional[str]

Link preview summary.

mentions: Optional[List[str]]

Mentioned user IDs, @room, or null for legacy messages that require text scanning.

reactions: Optional[List[Reaction]]

Reactions to the message, if any.

id: str

Reaction ID. When a participant can react more than once, the ID is the participant ID concatenated with the reaction key; otherwise it equals the participant ID.

participant_id: str

User ID of the participant who reacted.

reaction_key: str

The reaction key: an emoji (😄), a network-specific key, or a shortcode like “smiling-face”.

emoji: Optional[bool]

True if the reactionKey is an emoji.

img_url: Optional[str]

URL to the reaction’s image. May be temporary or available only on this device; download promptly if durable access is needed.

seen: Optional[Union[bool, datetime, Dict[str, Union[bool, datetime]], null]]

Read receipt state for this message, when available.

One of the following:

bool

datetime

ISO 8601 timestamp.

Dict[str, Union[bool, datetime]]

Group read receipt state keyed by participant ID.

One of the following:

bool

datetime

ISO 8601 timestamp.

sender_name: Optional[str]

Resolved sender display name.

send_status: Optional[SendStatus]

Message send status for this message, when reported by the bridge.

status: Literal["SUCCESS", "PENDING", "FAIL_RETRIABLE", "FAIL_PERMANENT"]

Current status of the message send attempt.

One of the following:

"SUCCESS"

"PENDING"

"FAIL_RETRIABLE"

"FAIL_PERMANENT"

timestamp: datetime

Timestamp for the send status event.

formatdate-time

delivered_to_users: Optional[List[str]]

User IDs the message was delivered to, when reported by the network.

internal_error: Optional[str]

Diagnostic error detail from the messaging network adapter. Do not show directly to users.

message: Optional[str]

Human-readable send status or failure message.

reason: Optional[str]

Machine-readable failure reason. Present when the send status is a failure.

text: Optional[str]

Rich-text message body if present.

type: Optional[Literal["TEXT", "NOTICE", "IMAGE", 7 more]]

Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

One of the following:

"TEXT"

"NOTICE"

"IMAGE"

"VIDEO"

"VOICE"

"AUDIO"

"FILE"

"STICKER"

"LOCATION"

"REACTION"

newest_cursor: Optional[str]

Cursor for fetching newer results (use with direction=‘after’). Opaque string; do not inspect.

oldest_cursor: Optional[str]

Cursor for fetching older results (use with direction=‘before’). Opaque string; do not inspect.