Skip to content
Beeper Developer Docs
Download Beeper
API Reference

Chats

Manage chats

Retrieve chat details
GET/v1/chats/{chatID}
Create a chat
POST/v1/chats
Start a direct chat
POST/v1/chats/start
List chats
GET/v1/chats
Search chats
GET/v1/chats/search
Archive or unarchive a chat
POST/v1/chats/{chatID}/archive
Update chat
PATCH/v1/chats/{chatID}
Mark a chat as read
POST/v1/chats/{chatID}/read
Mark a chat as unread
POST/v1/chats/{chatID}/unread
Notify anyway
POST/v1/chats/{chatID}/notify-anyway
ModelsExpand Collapse
Chat object { id, accountID, network, 21 more }
id: string

Unique identifier of the chat across Beeper.

accountID: string

Account ID this chat belongs to.

network: string

Display-only human-readable account/network name.

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

isAdmin: optional boolean

True if this participant has admin privileges in the chat.

isNetworkBot: optional boolean

True if this participant represents an automated network account.

isPending: optional boolean

True if this participant has been invited but has not joined yet.

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.

capabilities: optional object { allowedReactions, archive, attachments, 24 more }

Chat capabilities reported by the platform.

allowedReactions: optional array of string

Allowed Unicode reactions. Omitted means all emoji reactions are allowed.

archive: optional boolean

True if archive/unarchive is supported.

attachments: optional map[object { mimeTypes, caption, maxCaptionLength, 5 more } ]

Supported attachment message types and their per-type constraints, keyed by Matrix msgtype or pseudo-msgtype (for example m.image, m.video, org.matrix.msc3245.voice). Missing message types should be treated as rejected.

mimeTypes: map[-2 or -1 or 0 or 2 more]

Supported MIME types or MIME patterns for this file message type. Missing MIME types should be treated as rejected.

One of the following:
-2
-1
0
1
2
caption: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
maxCaptionLength: optional number

Maximum caption length when captions are supported.

maxDuration: optional number

Maximum audio or video duration in seconds.

maxHeight: optional number

Maximum image or video height in pixels.

maxSize: optional number

Maximum file size in bytes.

maxWidth: optional number

Maximum image or video width in pixels.

viewOnce: optional boolean

True if this file type can be sent as view-once media.

customEmojiReactions: optional boolean

True if custom emoji reactions are supported.

delete: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
deleteChat: optional boolean

True if deleting chats for the authenticated user is supported.

deleteChatForEveryone: optional boolean

True if deleting chats for everyone is supported.

deleteForMe: optional boolean

True if deleting messages only for the authenticated user is supported.

deleteMaxAge: optional number

Maximum message age for delete-for-everyone, in seconds.

disappearingTimer: optional object { omitEmptyTimer, timers, types }

Disappearing-message timer capabilities.

omitEmptyTimer: optional boolean

True if empty timer objects should be omitted from message content.

timers: optional array of number

Allowed disappearing timer values in milliseconds. Omitted means any timer is allowed.

types: optional array of "afterRead" or "afterSend"

Supported disappearing timer types.

One of the following:
"afterRead"
"afterSend"
edit: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
editMaxAge: optional number

Maximum message age for edits, in seconds.

editMaxCount: optional number

Maximum number of edits allowed for one message.

formatting: optional map[-2 or -1 or 0 or 2 more]

Supported rich-text formatting features keyed by feature name (for example bold, inline_code, code_block.syntax_highlighting). Omitted means no formatting support is advertised.

One of the following:
-2
-1
0
1
2
locationMessage: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
markAsUnread: optional boolean

True if marking chats unread is supported.

maxTextLength: optional number

Maximum length of normal text messages.

messageRequest: optional object { acceptWithButton, acceptWithMessage }

Message request capabilities.

acceptWithButton: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
acceptWithMessage: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
participantActions: optional object { ban, invite, kick, 2 more }

Participant management capabilities.

ban: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
invite: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
kick: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
leave: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
revokeInvite: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
poll: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
reaction: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
reactionCount: optional number

Maximum number of reactions allowed on a single message.

readReceipts: optional boolean

True if read receipts are supported.

reply: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
state: optional object { avatar, description, disappearingTimer, title }

Chat state update capabilities.

avatar: optional object { level }

Chat avatar state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
description: optional object { level }

Chat description/topic state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
disappearingTimer: optional object { level }

Disappearing-message timer state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
title: optional object { level }

Chat title state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
thread: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:
-2
-1
0
1
2
typingNotifications: optional boolean

True if typing notifications are supported.

description: optional string

Group chat description/topic when available.

draft: optional object { text, attachments }

Current draft object for this chat, or null when no draft is set.

text: string

Rich-text draft body as returned by Beeper.

attachments: optional map[object { id, type, audioDurationSeconds, 6 more } ]

Draft attachments keyed by attachment ID.

id: string

Draft attachment identifier.

type: "file" or "gif" or "recorded_audio"

Draft attachment type. GIF and recorded audio are mutually exclusive types.

One of the following:
"file"
"gif"
"recorded_audio"
audioDurationSeconds: optional number

Audio duration in seconds if known.

fileName: optional string

Original filename if available.

filePath: optional string

Local filesystem path for the draft attachment.

fileSize: optional number

File size in bytes if known.

mimeType: optional string

MIME type if known.

size: optional object { height, width }

Pixel dimensions of the attachment.

height: optional number
width: optional number
stickerID: optional string

Sticker identifier if the draft attachment is a sticker.

imgURL: optional string

Local filesystem path to the chat avatar image when available.

isArchived: optional boolean

True if chat is archived.

isLowPriority: optional boolean

True if chat is marked low priority.

isMarkedUnread: optional boolean

True if the chat was explicitly marked unread by the authenticated user.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

isReadOnly: optional boolean

True if messages cannot be sent in this chat.

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

messageExpirySeconds: optional number

Disappearing-message timer in seconds when available.

reminder: optional object { dismissOnIncomingMessage, remindAt }

Current reminder for this chat, or null when no reminder is set.

dismissOnIncomingMessage: optional boolean

Cancel reminder if someone messages in the chat.

remindAt: optional string

Timestamp when the reminder should trigger.

formatdate-time
snooze: optional object { snoozeUntil, userSnoozedAt }

Current snooze state for this chat, or null when no snooze is set.

snoozeUntil: optional string

Timestamp when the snooze expires.

formatdate-time
userSnoozedAt: optional string

Timestamp when the user set the snooze.

formatdate-time
unreadMentionsCount: optional number

Number of unread messages that mention the authenticated user or @room.

ChatCreateResponse = Chat { id, accountID, network, 21 more }
DeprecatedchatID: string
Use id instead.

DEPRECATED - use id instead. Compatibility alias for older clients.

Deprecatedstatus: optional "existing" or "created"
Inspect the returned Chat instead.

DEPRECATED - legacy start-chat status for older clients. New clients should inspect the returned Chat instead.

One of the following:
"existing"
"created"
ChatStartResponse = Chat { id, accountID, network, 21 more }
DeprecatedchatID: string
Use id instead.

DEPRECATED - use id instead. Compatibility alias for older clients.

Deprecatedstatus: optional "existing" or "created"
Inspect the returned Chat instead.

DEPRECATED - legacy start-chat status for older clients. New clients should inspect the returned Chat instead.

One of the following:
"existing"
"created"
ChatListResponse = Chat { id, accountID, network, 21 more }

Chat with optional last message preview.

preview: optional Message { id, accountID, chatID, 18 more }

Last message preview for this chat, if available.

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: optional array of Attachment { type, id, duration, 10 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 the download file endpoint 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 available only on 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 file. May be temporary or available only on this device; download promptly if durable access is needed.

transcription: optional object { engine, transcription, language }

Attachment transcription if available.

engine: string

Transcription engine.

transcription: string

Transcribed text.

language: optional string

Detected or selected language.

editedTimestamp: optional string

Timestamp when the message was edited, if known.

formatdate-time
isDeleted: optional boolean

True if the message has been deleted.

isHidden: optional boolean

True if the message is hidden from normal display.

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.

mentions: optional array of string

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

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

True if the reactionKey is an emoji.

imgURL: optional string

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

seen: optional boolean or string or map[boolean or string]

Read receipt state for this message, when available.

One of the following:
Boolean = boolean
Timestamp = string

ISO 8601 timestamp.

ByParticipant = map[boolean or string]

Group read receipt state keyed by participant ID.

One of the following:
Boolean = boolean
Timestamp = string

ISO 8601 timestamp.

senderName: optional string

Resolved sender display name.

sendStatus: optional object { status, timestamp, deliveredToUsers, 3 more }

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

status: "SUCCESS" or "PENDING" or "FAIL_RETRIABLE" or "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: optional array of string

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

internalError: optional string

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

message: optional string

Human-readable send status or failure message.

reason: optional string

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

text: optional string

Rich-text message body if present.

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/{reactionKey}
ModelsExpand Collapse
ReactionAddResponse object { chatID, messageID, reactionKey, 2 more }
chatID: string

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

messageID: string

Message ID.

reactionKey: string

Reaction key that was added.

success: true

Always true. Indicates the reaction was queued; failures return an error response.

transactionID: string

Transaction ID used for send tracking.

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

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

messageID: string

Message ID.

reactionKey: string

Reaction key that was removed.

success: true

Always true. Indicates the reaction removal was queued; failures return an error response.