Skip to content
Beeper Developer Docs
Download Beeper
API Reference

Shared

ModelsExpand Collapse
APIError { code, message, details }
code: string
message: string
details?: Record<string, unknown>
AppStateSnapshot { e2ee, state, matrix, verification }
e2ee: E2EE { crossSigning, firstSyncDone, hasBackedUpRecoveryKey, 6 more }

Encrypted messaging setup status.

crossSigning: boolean

Whether this account can verify trusted devices.

firstSyncDone: boolean

Whether the first encrypted message sync is complete.

hasBackedUpRecoveryKey: boolean

Whether the user confirmed that they saved their recovery key.

initialized: boolean

Whether encrypted messaging setup has started.

keyBackup: boolean

Whether encrypted message backup is available.

secrets: Secrets { masterKey, megolmBackupKey, recoveryKey, 2 more }

Encrypted messaging keys available on this device.

masterKey: boolean

Whether the account identity key is available.

megolmBackupKey: boolean

Whether the encrypted message backup key is available.

recoveryKey: boolean

Whether a recovery key is available.

selfSigningKey: boolean

Whether the device trust key is available.

userSigningKey: boolean

Whether the user trust key is available.

secretStorage: boolean

Whether secure key storage is available.

verified: boolean

Whether this device is trusted for encrypted messages.

recoveryKeyGeneratedAt?: number

Unix timestamp for when the recovery key was created.

state: "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?: Matrix { deviceID, homeserver, userID }

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

deviceID: string

Current device ID.

homeserver: string

Beeper homeserver URL for this account.

userID: string

Signed-in Beeper user ID.

verification?: Verification { id, availableActions, direction, 8 more }

Trusted device verification progress.

id: string

Verification ID to pass in verification action paths.

availableActions: Array<"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: "incoming" | "outgoing"

Whether this device started or received the verification.

One of the following:
"incoming"
"outgoing"
methods: Array<"qr" | "sas">

Verification methods supported for this transaction.

One of the following:
"qr"
"sas"
purpose: "login" | "device"

Why this verification exists.

One of the following:
"login"
"device"
state: "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?: Error { code, reason }

Verification error details, if verification stopped.

code: string

Verification error code.

reason: string

User-facing verification error message.

otherDevice?: OtherDevice { id, name }

Other device participating in verification.

id: string

Other device ID.

name?: string

Other device display name, if known.

otherUserID?: string

Other Beeper user participating in verification.

qr?: Qr { data }

QR verification data.

data: string

QR code payload to display for verification.

sas?: SAS { emojis, decimals }

Emoji or number comparison data for verification.

emojis: string

Emoji sequence to compare on both devices.

decimals?: string

Number sequence to compare on both devices.

Attachment { type, id, duration, 10 more }
type: "unknown" | "img" | "video" | "audio"

Attachment type.

One of the following:
"unknown"
"img"
"video"
"audio"
id?: string

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

duration?: number

Duration in seconds (audio/video).

fileName?: string

Original filename if available.

fileSize?: number

File size in bytes if known.

isGif?: boolean

True if the attachment is a GIF.

isSticker?: boolean

True if the attachment is a sticker.

isVoiceNote?: boolean

True if the attachment is a voice note.

mimeType?: string

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

posterImg?: string

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?: Size { height, width }

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

height?: number
width?: number
srcURL?: string

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?: Transcription { engine, transcription, language }

Attachment transcription if available.

engine: string

Transcription engine.

transcription: string

Transcribed text.

language?: string

Detected or selected language.

Error { code, message, details }
code: string

Machine-readable error code

message: string

Error message

details?: ValidationDetails { issues } | Record<string, unknown> | unknown

Additional error details for debugging

One of the following:
ValidationDetails { issues }

Validation error details

issues: Array<Issue>

List of validation issues

code: string

Validation issue code

message: string

Human-readable description of the validation issue

path: Array<string | number>

Path pointing to the invalid field within the payload

One of the following:
string
number
Record<string, unknown>
unknown
Message { id, accountID, chatID, 18 more }
id: string

Message ID.

accountID: string

Beeper account ID the message belongs to.

chatID: string

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

senderID: string

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

sortKey: string

A unique, sortable key used to sort messages.

timestamp: string

Message timestamp.

formatdate-time
attachments?: Array<Attachment { type, id, duration, 10 more } >

Attachments included with this message, if any.

type: "unknown" | "img" | "video" | "audio"

Attachment type.

One of the following:
"unknown"
"img"
"video"
"audio"
id?: string

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

duration?: number

Duration in seconds (audio/video).

fileName?: string

Original filename if available.

fileSize?: number

File size in bytes if known.

isGif?: boolean

True if the attachment is a GIF.

isSticker?: boolean

True if the attachment is a sticker.

isVoiceNote?: boolean

True if the attachment is a voice note.

mimeType?: string

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

posterImg?: string

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?: Size { height, width }

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

height?: number
width?: number
srcURL?: string

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?: Transcription { engine, transcription, language }

Attachment transcription if available.

engine: string

Transcription engine.

transcription: string

Transcribed text.

language?: string

Detected or selected language.

editedTimestamp?: string

Timestamp when the message was edited, if known.

formatdate-time
isDeleted?: boolean

True if the message has been deleted.

isHidden?: boolean

True if the message is hidden from normal display.

isSender?: boolean

True if the authenticated user sent the message.

isUnread?: boolean

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

linkedMessageID?: string

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

mentions?: Array<string> | null

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

reactions?: Array<Reaction { id, participantID, reactionKey, 2 more } >

Reactions to the message, if any.

id: string

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.

participantID: string

User ID of the participant who reacted.

reactionKey: string

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

emoji?: boolean

True if the reactionKey is an emoji.

imgURL?: string

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

seen?: boolean | string | Record<string, boolean | string>

Read receipt state for this message, when available.

One of the following:
boolean
string
Record<string, boolean | string>
boolean
string
senderName?: string

Resolved sender display name.

sendStatus?: SendStatus { status, timestamp, deliveredToUsers, 3 more }

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

status: "SUCCESS" | "PENDING" | "FAIL_RETRIABLE" | "FAIL_PERMANENT"

Current status of the message send attempt.

One of the following:
"SUCCESS"
"PENDING"
"FAIL_RETRIABLE"
"FAIL_PERMANENT"
timestamp: string

Timestamp for the send status event.

formatdate-time
deliveredToUsers?: Array<string>

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

internalError?: string

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

message?: string

Human-readable send status or failure message.

reason?: string

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

text?: string

Rich-text message body if present.

type?: "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"
Reaction { id, participantID, reactionKey, 2 more }
id: string

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.

participantID: string

User ID of the participant who reacted.

reactionKey: string

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

emoji?: boolean

True if the reactionKey is an emoji.

imgURL?: string

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

User { id, cannotMessage, email, 5 more }

User the account belongs to.

id: string

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

cannotMessage?: boolean

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?: string

Email address if known. Not guaranteed verified.

fullName?: string

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

imgURL?: string

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.

isSelf?: boolean

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

phoneNumber?: string

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

username?: string

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