Skip to content
Beeper Developer Docs
Download Beeper
API Reference

Shared

ModelsExpand Collapse
class APIError: …
code: str
message: str
details: Optional[Dict[str, Optional[object]]]
class AppStateSnapshot: …
e2ee: E2EE

Encrypted messaging setup status.

cross_signing: bool

Whether this account can verify trusted devices.

first_sync_done: bool

Whether the first encrypted message sync is complete.

has_backed_up_recovery_key: bool

Whether the user confirmed that they saved their recovery key.

initialized: bool

Whether encrypted messaging setup has started.

key_backup: bool

Whether encrypted message backup is available.

secrets: E2EESecrets

Encrypted messaging keys available on this device.

master_key: bool

Whether the account identity key is available.

megolm_backup_key: bool

Whether the encrypted message backup key is available.

recovery_key: bool

Whether a recovery key is available.

self_signing_key: bool

Whether the device trust key is available.

user_signing_key: bool

Whether the user trust key is available.

secret_storage: bool

Whether secure key storage is available.

verified: bool

Whether this device is trusted for encrypted messages.

recovery_key_generated_at: Optional[float]

Unix timestamp for when the recovery key was created.

state: Literal["needs-login", "initializing", "needs-cross-signing-setup", 4 more]

Current sign-in and encrypted messaging setup state for Beeper Desktop or Beeper Server.

One of the following:
"needs-login"
"initializing"
"needs-cross-signing-setup"
"needs-verification"
"needs-secrets"
"needs-first-sync"
"ready"
matrix: Optional[Matrix]

Signed-in account details. Omitted until sign-in is complete.

device_id: str

Current device ID.

homeserver: str

Beeper homeserver URL for this account.

user_id: str

Signed-in Beeper user ID.

verification: Optional[Verification]

Trusted device verification progress.

id: str

Verification ID to pass in verification action paths.

available_actions: List[Literal["accept", "cancel", "qr.confirmScanned", 2 more]]

Verification actions that are valid for the current state.

One of the following:
"accept"
"cancel"
"qr.confirmScanned"
"sas.start"
"sas.confirm"
direction: Literal["incoming", "outgoing"]

Whether this device started or received the verification.

One of the following:
"incoming"
"outgoing"
methods: List[Literal["qr", "sas"]]

Verification methods supported for this transaction.

One of the following:
"qr"
"sas"
purpose: Literal["login", "device"]

Why this verification exists.

One of the following:
"login"
"device"
state: Literal["requested", "ready", "sas_ready", 4 more]

Current trusted-device verification state.

One of the following:
"requested"
"ready"
"sas_ready"
"qr_scanned"
"done"
"cancelled"
"error"
error: Optional[VerificationError]

Verification error details, if verification stopped.

code: str

Verification error code.

reason: str

User-facing verification error message.

other_device: Optional[VerificationOtherDevice]

Other device participating in verification.

id: str

Other device ID.

name: Optional[str]

Other device display name, if known.

other_user_id: Optional[str]

Other Beeper user participating in verification.

qr: Optional[VerificationQR]

QR verification data.

data: str

QR code payload to display for verification.

sas: Optional[VerificationSAS]

Emoji or number comparison data for verification.

emojis: str

Emoji sequence to compare on both devices.

decimals: Optional[str]

Number sequence to compare on both devices.

class Attachment: …
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.

class AttachmentCapabilities: …

Capabilities for one attachment message type.

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.

class ChatCapabilities: …

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, AttachmentCapabilities]]

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[DisappearingTimer]

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[MessageRequest]

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[ParticipantActions]

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[ChatStateCapabilities]

Chat state update capabilities.

avatar: Optional[Avatar]

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[Description]

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[DisappearingTimer]

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[Title]

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.

class ChatDraft: …

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, DraftAttachment]]

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[Size]

Pixel dimensions of the attachment.

height: Optional[float]
width: Optional[float]
sticker_id: Optional[str]

Sticker identifier if the draft attachment is a sticker.

class ChatStateCapabilities: …

Chat state update capabilities.

avatar: Optional[Avatar]

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[Description]

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[DisappearingTimer]

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[Title]

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
class DraftAttachment: …
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[Size]

Pixel dimensions of the attachment.

height: Optional[float]
width: Optional[float]
sticker_id: Optional[str]

Sticker identifier if the draft attachment is a sticker.

class Error: …
code: str

Machine-readable error code

message: str

Error message

details: Optional[Details]

Additional error details for debugging

One of the following:
class DetailsValidationDetails: …

Validation error details

issues: List[DetailsValidationDetailsIssue]

List of validation issues

code: str

Validation issue code

message: str

Human-readable description of the validation issue

path: List[Union[str, float]]

Path pointing to the invalid field within the payload

One of the following:
str
float
Dict[str, Optional[object]]

Additional error context

Optional[object]

Arbitrary details payload supplied by the server

class Message: …
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"
class Reaction: …
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.

class 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.

class User: …

User the account belongs to.

id: str

Stable Beeper user ID. Use as the primary key when referencing a person.

cannot_message: Optional[bool]

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

email: Optional[str]

Email address if known. Not guaranteed verified.

full_name: Optional[str]

Display name as shown in clients (e.g., ‘Alice Example’). May include emojis.

img_url: Optional[str]

Avatar image URL if available. This may be a remote URL, media URL, data URL, or local file URL depending on the source. May be temporary or available only on this device; download promptly if durable access is needed.

is_self: Optional[bool]

True if this user represents the authenticated account’s own identity.

phone_number: Optional[str]

User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown.

username: Optional[str]

Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique.