Skip to content
Beeper Developer Docs
Download Beeper
API Reference

Chats

Manage chats

Retrieve chat details
chats.retrieve(strchat_id, ChatRetrieveParams**kwargs) -> Chat
GET/v1/chats/{chatID}
Create a chat
chats.create(ChatCreateParams**kwargs) -> ChatCreateResponse
POST/v1/chats
Start a direct chat
chats.start(ChatStartParams**kwargs) -> ChatStartResponse
POST/v1/chats/start
List chats
chats.list(ChatListParams**kwargs) -> SyncCursorNoLimit[ChatListResponse]
GET/v1/chats
Search chats
chats.search(ChatSearchParams**kwargs) -> SyncCursorSearch[Chat]
GET/v1/chats/search
Archive or unarchive a chat
chats.archive(strchat_id, ChatArchiveParams**kwargs)
POST/v1/chats/{chatID}/archive
Update chat
chats.update(strchat_id, ChatUpdateParams**kwargs) -> Chat
PATCH/v1/chats/{chatID}
Mark a chat as read
chats.mark_read(strchat_id, ChatMarkReadParams**kwargs) -> Chat
POST/v1/chats/{chatID}/read
Mark a chat as unread
chats.mark_unread(strchat_id, ChatMarkUnreadParams**kwargs) -> Chat
POST/v1/chats/{chatID}/unread
Notify anyway
chats.notify_anyway(strchat_id) -> Chat
POST/v1/chats/{chatID}/notify-anyway
ModelsExpand Collapse
class Chat: …
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.

class ChatCreateResponse: …
Deprecatedchat_id: str
Use id instead.

DEPRECATED - use id instead. Compatibility alias for older clients.

Deprecatedstatus: Optional[Literal["existing", "created"]]
Inspect the returned Chat instead.

DEPRECATED - legacy start-chat status for older clients. New clients should inspect the returned Chat instead.

One of the following:
"existing"
"created"
class ChatStartResponse: …
Deprecatedchat_id: str
Use id instead.

DEPRECATED - use id instead. Compatibility alias for older clients.

Deprecatedstatus: Optional[Literal["existing", "created"]]
Inspect the returned Chat instead.

DEPRECATED - legacy start-chat status for older clients. New clients should inspect the returned Chat instead.

One of the following:
"existing"
"created"
class ChatListResponse: …

Chat with optional last message preview.

preview: Optional[Message]

Last message preview for this chat, if available.

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.

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"

ChatsReminders

Manage reminders for chats

Create a chat reminder
chats.reminders.create(strchat_id, ReminderCreateParams**kwargs)
POST/v1/chats/{chatID}/reminders
Delete a chat reminder
chats.reminders.delete(strchat_id)
DELETE/v1/chats/{chatID}/reminders

ChatsMessages

Manage chat messages

ChatsMessagesReactions

Manage message reactions

Add a reaction
chats.messages.reactions.add(strmessage_id, ReactionAddParams**kwargs) -> ReactionAddResponse
POST/v1/chats/{chatID}/messages/{messageID}/reactions
Remove a reaction
chats.messages.reactions.delete(strreaction_key, ReactionDeleteParams**kwargs) -> ReactionDeleteResponse
DELETE/v1/chats/{chatID}/messages/{messageID}/reactions/{reactionKey}
ModelsExpand Collapse
class ReactionAddResponse: …
chat_id: str

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

message_id: str

Message ID.

reaction_key: str

Reaction key that was added.

success: Literal[true]

Always true. Indicates the reaction was queued; failures return an error response.

transaction_id: str

Transaction ID used for send tracking.

class ReactionDeleteResponse: …
chat_id: str

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

message_id: str

Message ID.

reaction_key: str

Reaction key that was removed.

success: Literal[true]

Always true. Indicates the reaction removal was queued; failures return an error response.