Skip to content
Beeper Developer Docs
Download Beeper
API Reference

Chats

Manage chats

Retrieve chat details
GET/v1/chats/{chatID}
Create or start a chat
POST/v1/chats
List chats
GET/v1/chats
Search chats
GET/v1/chats/search
Archive or unarchive a chat
POST/v1/chats/{chatID}/archive
ModelsExpand Collapse
Chat object { id, accountID, participants, 9 more }
id: string

Unique identifier of the chat across Beeper.

accountID: string

Account ID this chat belongs to.

participants: object { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: array of 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: optional 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: optional string

Email address if known. Not guaranteed verified.

fullName: optional string

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

imgURL: optional string

Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

isSelf: optional boolean

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

phoneNumber: optional string

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

username: optional 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" or "group"

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

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

Number of unread messages.

isArchived: optional boolean

True if chat is archived.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

lastActivity: optional string

Timestamp of last activity.

formatdate-time
lastReadMessageSortKey: optional string

Last read message sortKey.

localChatID: optional string

Local chat ID specific to this Beeper Desktop installation.

ChatCreateResponse object { chatID, status }
chatID: string

Newly created chat ID.

status: optional "existing" or "created"

Only returned in start mode. ‘existing’ means an existing chat was reused; ‘created’ means a new chat was created.

One of the following:
"existing"
"created"
ChatListResponse = Chat { id, accountID, participants, 9 more }
preview: optional Message { id, accountID, chatID, 11 more }

Last message preview for this chat, if available.

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: optional array of Attachment { type, id, duration, 9 more }

Attachments included with this message, if any.

type: "unknown" or "img" or "video" or "audio"

Attachment type.

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

Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path.

duration: optional number

Duration in seconds (audio/video).

fileName: optional string

Original filename if available.

fileSize: optional number

File size in bytes if known.

isGif: optional boolean

True if the attachment is a GIF.

isSticker: optional boolean

True if the attachment is a sticker.

isVoiceNote: optional boolean

True if the attachment is a voice note.

mimeType: optional string

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

posterImg: optional 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: optional object { height, width }

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

height: optional number
width: optional number
srcURL: optional 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: optional boolean

True if the authenticated user sent the message.

isUnread: optional boolean

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

linkedMessageID: optional string

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

reactions: optional array of 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: optional boolean

True if the reactionKey is an emoji.

imgURL: optional string

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

senderName: optional string

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

text: optional string

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

type: optional "TEXT" or "NOTICE" or "IMAGE" or 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"

ChatsReminders

Manage reminders for chats

Create a chat reminder
POST/v1/chats/{chatID}/reminders
Delete a chat reminder
DELETE/v1/chats/{chatID}/reminders

ChatsMessages

Manage chat messages

ChatsMessagesReactions

Manage message reactions

Add a reaction
POST/v1/chats/{chatID}/messages/{messageID}/reactions
Remove a reaction
DELETE/v1/chats/{chatID}/messages/{messageID}/reactions
ModelsExpand Collapse
ReactionAddResponse object { chatID, messageID, reactionKey, 2 more }
chatID: string

Unique identifier of the chat.

messageID: string

Message ID.

reactionKey: string

Reaction key that was added

success: true

Whether the reaction was successfully added

transactionID: string

Transaction ID used for the reaction event

ReactionDeleteResponse object { chatID, messageID, reactionKey, success }
chatID: string

Unique identifier of the chat.

messageID: string

Message ID.

reactionKey: string

Reaction key that was removed

success: true

Whether the reaction was successfully removed