API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Shared

ModelsExpand Collapse

type APIError struct{…}

Code string

Message string

Details map[string, any]Optional

type AppStateSnapshot struct{…}

E2EE AppStateSnapshotE2EE

Encrypted messaging setup status.

CrossSigning bool

Whether this account can verify trusted devices.

FirstSyncDone bool

Whether the first encrypted message sync is complete.

HasBackedUpRecoveryKey bool

Whether the user confirmed that they saved their recovery key.

Initialized bool

Whether encrypted messaging setup has started.

KeyBackup bool

Whether encrypted message backup is available.

Secrets AppStateSnapshotE2EESecrets

Encrypted messaging keys available on this device.

MasterKey bool

Whether the account identity key is available.

MegolmBackupKey bool

Whether the encrypted message backup key is available.

RecoveryKey bool

Whether a recovery key is available.

SelfSigningKey bool

Whether the device trust key is available.

UserSigningKey bool

Whether the user trust key is available.

SecretStorage bool

Whether secure key storage is available.

Verified bool

Whether this device is trusted for encrypted messages.

RecoveryKeyGeneratedAt float64Optional

Unix timestamp for when the recovery key was created.

State AppStateSnapshotState

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

One of the following:

const AppStateSnapshotStateNeedsLogin AppStateSnapshotState = "needs-login"

const AppStateSnapshotStateInitializing AppStateSnapshotState = "initializing"

const AppStateSnapshotStateNeedsCrossSigningSetup AppStateSnapshotState = "needs-cross-signing-setup"

const AppStateSnapshotStateNeedsVerification AppStateSnapshotState = "needs-verification"

const AppStateSnapshotStateNeedsSecrets AppStateSnapshotState = "needs-secrets"

const AppStateSnapshotStateNeedsFirstSync AppStateSnapshotState = "needs-first-sync"

const AppStateSnapshotStateReady AppStateSnapshotState = "ready"

Matrix AppStateSnapshotMatrixOptional

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 AppStateSnapshotVerificationOptional

Trusted device verification progress.

ID string

Verification ID to pass in verification action paths.

AvailableActions []string

Verification actions that are valid for the current state.

One of the following:

const AppStateSnapshotVerificationAvailableActionAccept AppStateSnapshotVerificationAvailableAction = "accept"

const AppStateSnapshotVerificationAvailableActionCancel AppStateSnapshotVerificationAvailableAction = "cancel"

const AppStateSnapshotVerificationAvailableActionQrConfirmScanned AppStateSnapshotVerificationAvailableAction = "qr.confirmScanned"

const AppStateSnapshotVerificationAvailableActionSASStart AppStateSnapshotVerificationAvailableAction = "sas.start"

const AppStateSnapshotVerificationAvailableActionSASConfirm AppStateSnapshotVerificationAvailableAction = "sas.confirm"

Direction string

Whether this device started or received the verification.

One of the following:

const AppStateSnapshotVerificationDirectionIncoming AppStateSnapshotVerificationDirection = "incoming"

const AppStateSnapshotVerificationDirectionOutgoing AppStateSnapshotVerificationDirection = "outgoing"

Methods []string

Verification methods supported for this transaction.

One of the following:

const AppStateSnapshotVerificationMethodQr AppStateSnapshotVerificationMethod = "qr"

const AppStateSnapshotVerificationMethodSAS AppStateSnapshotVerificationMethod = "sas"

Purpose string

Why this verification exists.

One of the following:

const AppStateSnapshotVerificationPurposeLogin AppStateSnapshotVerificationPurpose = "login"

const AppStateSnapshotVerificationPurposeDevice AppStateSnapshotVerificationPurpose = "device"

State string

Current trusted-device verification state.

One of the following:

const AppStateSnapshotVerificationStateRequested AppStateSnapshotVerificationState = "requested"

const AppStateSnapshotVerificationStateReady AppStateSnapshotVerificationState = "ready"

const AppStateSnapshotVerificationStateSASReady AppStateSnapshotVerificationState = "sas_ready"

const AppStateSnapshotVerificationStateQrScanned AppStateSnapshotVerificationState = "qr_scanned"

const AppStateSnapshotVerificationStateDone AppStateSnapshotVerificationState = "done"

const AppStateSnapshotVerificationStateCancelled AppStateSnapshotVerificationState = "cancelled"

const AppStateSnapshotVerificationStateError AppStateSnapshotVerificationState = "error"

Error AppStateSnapshotVerificationErrorOptional

Verification error details, if verification stopped.

Code string

Verification error code.

Reason string

User-facing verification error message.

OtherDevice AppStateSnapshotVerificationOtherDeviceOptional

Other device participating in verification.

ID string

Other device ID.

Name stringOptional

Other device display name, if known.

OtherUserID stringOptional

Other Beeper user participating in verification.

Qr AppStateSnapshotVerificationQrOptional

QR verification data.

Data string

QR code payload to display for verification.

SAS AppStateSnapshotVerificationSASOptional

Emoji or number comparison data for verification.

Emojis string

Emoji sequence to compare on both devices.

Decimals stringOptional

Number sequence to compare on both devices.

type Attachment struct{…}

Type AttachmentType

Attachment type.

One of the following:

const AttachmentTypeUnknown AttachmentType = "unknown"

const AttachmentTypeImg AttachmentType = "img"

const AttachmentTypeVideo AttachmentType = "video"

const AttachmentTypeAudio AttachmentType = "audio"

ID stringOptional

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

Duration float64Optional

Duration in seconds (audio/video).

FileName stringOptional

Original filename if available.

FileSize float64Optional

File size in bytes if known.

IsGif boolOptional

True if the attachment is a GIF.

IsSticker boolOptional

True if the attachment is a sticker.

IsVoiceNote boolOptional

True if the attachment is a voice note.

MimeType stringOptional

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

PosterImg stringOptional

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 AttachmentSizeOptional

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

Height float64Optional

Width float64Optional

SrcURL stringOptional

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 AttachmentTranscriptionOptional

Attachment transcription if available.

Engine string

Transcription engine.

Transcription string

Transcribed text.

Language stringOptional

Detected or selected language.

type Error struct{…}

Code string

Machine-readable error code

Message string

Error message

Details ErrorDetailsUnionOptional

Additional error details for debugging

One of the following:

ErrorDetailsValidationDetails

Issues []ErrorDetailsValidationDetailsIssue

List of validation issues

Code string

Validation issue code

Message string

Human-readable description of the validation issue

Path []ErrorDetailsValidationDetailsIssuePathUnion

Path pointing to the invalid field within the payload

One of the following:

string

float64

map[string, any]

type Message struct{…}

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 Time

Message timestamp.

formatdate-time

Attachments []AttachmentOptional

Attachments included with this message, if any.

Type AttachmentType

Attachment type.

One of the following:

const AttachmentTypeUnknown AttachmentType = "unknown"

const AttachmentTypeImg AttachmentType = "img"

const AttachmentTypeVideo AttachmentType = "video"

const AttachmentTypeAudio AttachmentType = "audio"

ID stringOptional

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

Duration float64Optional

Duration in seconds (audio/video).

FileName stringOptional

Original filename if available.

FileSize float64Optional

File size in bytes if known.

IsGif boolOptional

True if the attachment is a GIF.

IsSticker boolOptional

True if the attachment is a sticker.

IsVoiceNote boolOptional

True if the attachment is a voice note.

MimeType stringOptional

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

PosterImg stringOptional

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 AttachmentSizeOptional

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

Height float64Optional

Width float64Optional

SrcURL stringOptional

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 AttachmentTranscriptionOptional

Attachment transcription if available.

Engine string

Transcription engine.

Transcription string

Transcribed text.

Language stringOptional

Detected or selected language.

EditedTimestamp TimeOptional

Timestamp when the message was edited, if known.

formatdate-time

IsDeleted boolOptional

True if the message has been deleted.

IsHidden boolOptional

True if the message is hidden from normal display.

IsSender boolOptional

True if the authenticated user sent the message.

IsUnread boolOptional

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

LinkedMessageID stringOptional

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

Links []MessageLinkOptional

Link previews included with this message, if any.

Title string

Link preview title.

URL string

Resolved link URL.

Favicon stringOptional

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

Img stringOptional

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

ImgSize MessageLinkImgSizeOptional

Preview image dimensions.

Height float64Optional

Width float64Optional

OriginalURL stringOptional

Original URL when the displayed URL is shortened or redirected.

Summary stringOptional

Link preview summary.

Mentions []stringOptional

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

Reactions []ReactionOptional

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 boolOptional

True if the reactionKey is an emoji.

ImgURL stringOptional

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

Seen MessageSeenUnionOptional

Read receipt state for this message, when available.

One of the following:

bool

Time

type MessageSeenByParticipant map[string, MessageSeenByParticipantItemUnion]

Group read receipt state keyed by participant ID.

One of the following:

bool

Time

SenderName stringOptional

Resolved sender display name.

SendStatus MessageSendStatusOptional

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

Status string

Current status of the message send attempt.

One of the following:

const MessageSendStatusStatusSuccess MessageSendStatusStatus = "SUCCESS"

const MessageSendStatusStatusPending MessageSendStatusStatus = "PENDING"

const MessageSendStatusStatusFailRetriable MessageSendStatusStatus = "FAIL_RETRIABLE"

const MessageSendStatusStatusFailPermanent MessageSendStatusStatus = "FAIL_PERMANENT"

Timestamp Time

Timestamp for the send status event.

formatdate-time

DeliveredToUsers []stringOptional

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

InternalError stringOptional

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

Message stringOptional

Human-readable send status or failure message.

Reason stringOptional

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

Text stringOptional

Rich-text message body if present.

Type MessageTypeOptional

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

One of the following:

const MessageTypeText MessageType = "TEXT"

const MessageTypeNotice MessageType = "NOTICE"

const MessageTypeImage MessageType = "IMAGE"

const MessageTypeVideo MessageType = "VIDEO"

const MessageTypeVoice MessageType = "VOICE"

const MessageTypeAudio MessageType = "AUDIO"

const MessageTypeFile MessageType = "FILE"

const MessageTypeSticker MessageType = "STICKER"

const MessageTypeLocation MessageType = "LOCATION"

const MessageTypeReaction MessageType = "REACTION"

type Reaction struct{…}

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 boolOptional

True if the reactionKey is an emoji.

ImgURL stringOptional

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

type User struct{…}

User the account belongs to.

ID string

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

CannotMessage boolOptional

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 stringOptional

Email address if known. Not guaranteed verified.

FullName stringOptional

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

ImgURL stringOptional

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 boolOptional

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

PhoneNumber stringOptional

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

Username stringOptional

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