Skip to content
Beeper Developer Docs
Download Beeper
API Reference

Client

Control the Beeper Desktop application

Focus Beeper Desktop app
client.focus(FocusParams { chatID, draftAttachmentPath, draftText, messageID } body?, RequestOptionsoptions?): FocusResponse { success }
POST/v1/focus
Search
client.search(SearchParams { query } query, RequestOptionsoptions?): SearchResponse { results }
GET/v1/search
ModelsExpand Collapse
FocusResponse { success }

Response indicating successful app focus action.

success: boolean

Whether the app was successfully opened/focused.

SearchResponse { results }
results: Results { chats, in_groups, messages }
chats: Array<Chat { id, accountID, participants, 9 more } >

Top chat results.

id: string

Unique identifier of the chat across Beeper.

accountID: string

Account ID this chat belongs to.

participants: Participants { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: Array<User { id, cannotMessage, email, 5 more } >

Participants returned for this chat (limited by the request; may be a subset).

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. May be temporary or local-only to 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.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" | "group"

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

One of the following:
"single"
"group"
unreadCount: number

Number of unread messages.

isArchived?: boolean

True if chat is archived.

isMuted?: boolean

True if chat notifications are muted.

isPinned?: boolean

True if chat is pinned.

lastActivity?: string

Timestamp of last activity.

formatdate-time
lastReadMessageSortKey?: string

Last read message sortKey.

localChatID?: string | null

Local chat ID specific to this Beeper Desktop installation.

in_groups: Array<Chat { id, accountID, participants, 9 more } >

Top group results by participant matches.

id: string

Unique identifier of the chat across Beeper.

accountID: string

Account ID this chat belongs to.

participants: Participants { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: Array<User { id, cannotMessage, email, 5 more } >

Participants returned for this chat (limited by the request; may be a subset).

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. May be temporary or local-only to 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.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" | "group"

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

One of the following:
"single"
"group"
unreadCount: number

Number of unread messages.

isArchived?: boolean

True if chat is archived.

isMuted?: boolean

True if chat notifications are muted.

isPinned?: boolean

True if chat is pinned.

lastActivity?: string

Timestamp of last activity.

formatdate-time
lastReadMessageSortKey?: string

Last read message sortKey.

localChatID?: string | null

Local chat ID specific to this Beeper Desktop installation.

messages: Messages { chats, hasMore, items, 2 more }
chats: Record<string, Chat { id, accountID, participants, 9 more } >

Map of chatID -> chat details for chats referenced in items.

id: string

Unique identifier of the chat across Beeper.

accountID: string

Account ID this chat belongs to.

participants: Participants { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: Array<User { id, cannotMessage, email, 5 more } >

Participants returned for this chat (limited by the request; may be a subset).

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. May be temporary or local-only to 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.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" | "group"

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

One of the following:
"single"
"group"
unreadCount: number

Number of unread messages.

isArchived?: boolean

True if chat is archived.

isMuted?: boolean

True if chat notifications are muted.

isPinned?: boolean

True if chat is pinned.

lastActivity?: string

Timestamp of last activity.

formatdate-time
lastReadMessageSortKey?: string

Last read message sortKey.

localChatID?: string | null

Local chat ID specific to this Beeper Desktop installation.

hasMore: boolean

True if additional results can be fetched using the provided cursors.

items: Array<Message { id, accountID, chatID, 11 more } >

Messages matching the query and filters.

id: string

Message ID.

accountID: string

Beeper account ID the message belongs to.

chatID: string

Unique identifier of the chat.

senderID: string

Sender user ID.

sortKey: string

A unique, sortable key used to sort messages.

timestamp: string

Message timestamp.

formatdate-time
attachments?: Array<Attachment { type, id, duration, 9 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 with /v1/assets/download 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 local-only to 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 asset. May be temporary or local-only to this device; download promptly if durable access is needed.

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.

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

Reactions to the message, if any.

id: string

Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise.

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 local-only to this device; download promptly if durable access is needed.

senderName?: string

Resolved sender display name (impersonator/full name/username/participant name).

text?: string

Plain-text body if present. May include a JSON fallback with text entities for rich messages.

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"
newestCursor: string | null

Cursor for fetching newer results (use with direction=‘after’). Opaque string; do not inspect.

oldestCursor: string | null

Cursor for fetching older results (use with direction=‘before’). Opaque string; do not inspect.