Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Messages

Retrieve a message

messages.retrieve(strmessage_id, MessageRetrieveParams**kwargs) -> Message
GET/v1/chats/{chatID}/messages/{messageID}

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

ParametersExpand Collapse
chat_id: str

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

message_id: str

Message ID.

ReturnsExpand Collapse
class Message: …
id: str

Message ID.

account_id: str

Beeper account ID the message belongs to.

chat_id: str

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

sender_id: str

Matrix-style fully-qualified sender user ID, usually including a bridge prefix and homeserver.

sort_key: str

A unique, sortable key used to sort messages.

timestamp: datetime

Message timestamp.

formatdate-time
attachments: Optional[List[Attachment]]

Attachments included with this message, if any.

type: Literal["unknown", "img", "video", "audio"]

Attachment type.

One of the following:
"unknown"
"img"
"video"
"audio"
id: Optional[str]

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

duration: Optional[float]

Duration in seconds (audio/video).

file_name: Optional[str]

Original filename if available.

file_size: Optional[float]

File size in bytes if known.

is_gif: Optional[bool]

True if the attachment is a GIF.

is_sticker: Optional[bool]

True if the attachment is a sticker.

is_voice_note: Optional[bool]

True if the attachment is a voice note.

mime_type: Optional[str]

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

poster_img: Optional[str]

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[Size]

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

height: Optional[float]
width: Optional[float]
src_url: Optional[str]

Public URL or local file path to fetch the file. May be temporary or local-only to this device; download promptly if durable access is needed.

transcription: Optional[Transcription]

Attachment transcription if available.

engine: str

Transcription engine.

transcription: str

Transcribed text.

language: Optional[str]

Detected or selected language.

edited_timestamp: Optional[datetime]

Timestamp when the message was edited, if known.

formatdate-time
is_deleted: Optional[bool]

True if the message has been deleted.

is_hidden: Optional[bool]

True if the message is hidden from normal display.

is_sender: Optional[bool]

True if the authenticated user sent the message.

is_unread: Optional[bool]

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

linked_message_id: Optional[str]

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

mentions: Optional[List[str]]

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

reactions: Optional[List[Reaction]]

Reactions to the message, if any.

id: str

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.

participant_id: str

User ID of the participant who reacted.

reaction_key: str

The reaction key: an emoji (😄), a network-specific key, or a shortcode like “smiling-face”.

emoji: Optional[bool]

True if the reactionKey is an emoji.

img_url: Optional[str]

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

seen: Optional[Union[bool, datetime, Dict[str, Union[bool, datetime]], null]]

Read receipt state for this message, when available.

One of the following:
bool
datetime

ISO 8601 timestamp.

Dict[str, Union[bool, datetime]]

Group read receipt state keyed by participant ID.

One of the following:
bool
datetime

ISO 8601 timestamp.

sender_name: Optional[str]

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

send_status: Optional[SendStatus]

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

status: Literal["SUCCESS", "PENDING", "FAIL_RETRIABLE", "FAIL_PERMANENT"]

Current status of the message send attempt.

One of the following:
"SUCCESS"
"PENDING"
"FAIL_RETRIABLE"
"FAIL_PERMANENT"
timestamp: datetime

Timestamp for the send status event.

formatdate-time
delivered_to_users: Optional[List[str]]

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

internal_error: Optional[str]

Internal bridge error detail. Intended for diagnostics, not end-user display.

message: Optional[str]

Human-readable send status or failure message.

reason: Optional[str]

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

text: Optional[str]

Matrix HTML body if present.

type: Optional[Literal["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"

Retrieve a message

import os
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop(
    access_token=os.environ.get("BEEPER_ACCESS_TOKEN"),  # This is the default and can be omitted
)
message = client.messages.retrieve(
    message_id="1343993",
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
)
print(message.id)
{
  "id": "241392",
  "accountID": "discordgo",
  "chatID": "!discord_109876543210987654:beeper.com",
  "senderID": "@discord_221590782384013314:beeper.com",
  "sortKey": "455171049984",
  "timestamp": "2026-05-05T20:20:12.497Z",
  "attachments": [
    {
      "type": "unknown",
      "id": "id",
      "duration": 0,
      "fileName": "fileName",
      "fileSize": 0,
      "isGif": true,
      "isSticker": true,
      "isVoiceNote": true,
      "mimeType": "mimeType",
      "posterImg": "posterImg",
      "size": {
        "height": 0,
        "width": 0
      },
      "srcURL": "srcURL",
      "transcription": {
        "engine": "engine",
        "transcription": "transcription",
        "language": "language"
      }
    }
  ],
  "editedTimestamp": "2025-08-31T23:30:12.520Z",
  "isDeleted": false,
  "isHidden": true,
  "isSender": false,
  "isUnread": false,
  "linkedMessageID": "1343993",
  "links": [
    {
      "title": "title",
      "url": "url",
      "favicon": "favicon",
      "img": "img",
      "imgSize": {
        "height": 0,
        "width": 0
      },
      "originalURL": "originalURL",
      "summary": "summary"
    }
  ],
  "mentions": [
    "@discord_337451892017545216:beeper.com"
  ],
  "reactions": [
    {
      "id": "id",
      "participantID": "participantID",
      "reactionKey": "reactionKey",
      "emoji": true,
      "imgURL": "imgURL"
    }
  ],
  "seen": true,
  "senderName": "Kishan Bagaria",
  "sendStatus": {
    "status": "SUCCESS",
    "timestamp": "2025-08-31T23:30:12.520Z",
    "deliveredToUsers": [
      "string"
    ],
    "internalError": "internalError",
    "message": "message",
    "reason": "reason"
  },
  "text": "The OAuth fix is deployed. Can you verify the desktop flow?",
  "type": "TEXT"
}
Returns Examples
{
  "id": "241392",
  "accountID": "discordgo",
  "chatID": "!discord_109876543210987654:beeper.com",
  "senderID": "@discord_221590782384013314:beeper.com",
  "sortKey": "455171049984",
  "timestamp": "2026-05-05T20:20:12.497Z",
  "attachments": [
    {
      "type": "unknown",
      "id": "id",
      "duration": 0,
      "fileName": "fileName",
      "fileSize": 0,
      "isGif": true,
      "isSticker": true,
      "isVoiceNote": true,
      "mimeType": "mimeType",
      "posterImg": "posterImg",
      "size": {
        "height": 0,
        "width": 0
      },
      "srcURL": "srcURL",
      "transcription": {
        "engine": "engine",
        "transcription": "transcription",
        "language": "language"
      }
    }
  ],
  "editedTimestamp": "2025-08-31T23:30:12.520Z",
  "isDeleted": false,
  "isHidden": true,
  "isSender": false,
  "isUnread": false,
  "linkedMessageID": "1343993",
  "links": [
    {
      "title": "title",
      "url": "url",
      "favicon": "favicon",
      "img": "img",
      "imgSize": {
        "height": 0,
        "width": 0
      },
      "originalURL": "originalURL",
      "summary": "summary"
    }
  ],
  "mentions": [
    "@discord_337451892017545216:beeper.com"
  ],
  "reactions": [
    {
      "id": "id",
      "participantID": "participantID",
      "reactionKey": "reactionKey",
      "emoji": true,
      "imgURL": "imgURL"
    }
  ],
  "seen": true,
  "senderName": "Kishan Bagaria",
  "sendStatus": {
    "status": "SUCCESS",
    "timestamp": "2025-08-31T23:30:12.520Z",
    "deliveredToUsers": [
      "string"
    ],
    "internalError": "internalError",
    "message": "message",
    "reason": "reason"
  },
  "text": "The OAuth fix is deployed. Can you verify the desktop flow?",
  "type": "TEXT"
}