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