Retrieve a message

$ beeper-desktop messages retrieve

GET/v1/chats/{chatID}/messages/{messageID}

Retrieve a message by final message ID, pendingMessageID, or Matrix event ID. chatID may be a Beeper chat ID or a local chat ID.

ParametersExpand Collapse

--chat-id: string

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

--message-id: string

Message ID.

ReturnsExpand Collapse

message: object { 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.

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.

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

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.

links: optional array of object { title, url, favicon, 4 more }

Link previews included with this message, if any.

title: string

Link preview title.

url: string

Resolved link URL.

favicon: optional string

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

img: optional string

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

imgSize: optional object { height, width }

Preview image dimensions.

height: optional number

width: optional number

originalURL: optional string

Original URL when the displayed URL is shortened or redirected.

summary: optional string

Link preview summary.

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.

boolean: boolean

timestamp: string

ISO 8601 timestamp.

by_participant: map[boolean or string]

Group read receipt state keyed by participant ID.

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.

"SUCCESS"

"PENDING"

"FAIL_RETRIABLE"

"FAIL_PERMANENT"

timestamp: string

Timestamp for the send status event.

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.

"TEXT"

"NOTICE"

"IMAGE"

"VIDEO"

"VOICE"

"AUDIO"

"FILE"

"STICKER"

"LOCATION"

"REACTION"