List

API Reference

Messages

List messages

messages.list(, ) -> SyncCursorList[Message]

get/v1/chats/{chatID}/messages

List all messages in a chat with cursor-based pagination. Sorted by timestamp.

ParametersExpand Collapse

chat_id: str

Unique identifier of the chat.

cursor: Optional[str]

Opaque pagination cursor; do not inspect. Use together with 'direction'.

direction: Optional[Literal["after", "before"]]

Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided.

Accepts one of the following:

"after"

"before"

ReturnsExpand Collapse

class Message: …

id: str

Message ID.

account_id: str

Beeper account ID the message belongs to.

chat_id: str

Unique identifier of the chat.

sender_id: str

Sender user ID.

sort_key: str

A unique 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.

Accepts one of the following:

"unknown"

"img"

"video"

"audio"

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

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.

reactions: Optional[List[Reaction]]

Reactions to the message, if any.

id: str

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

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.

sender_name: Optional[str]

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

text: Optional[str]

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

List messages

from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop(
    access_token="My Access Token",
)
page = client.messages.list(
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
)
page = page.items[0]
print(page.id)

{
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": "821744079",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "attachments": [
        {
          "type": "unknown",
          "duration": 0,
          "fileName": "fileName",
          "fileSize": 0,
          "isGif": true,
          "isSticker": true,
          "isVoiceNote": true,
          "mimeType": "mimeType",
          "posterImg": "posterImg",
          "size": {
            "height": 0,
            "width": 0
          },
          "srcURL": "srcURL"
        }
      ],
      "isSender": false,
      "isUnread": false,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?"
    }
  ]
}

Returns Examples

{
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": "821744079",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "attachments": [
        {
          "type": "unknown",
          "duration": 0,
          "fileName": "fileName",
          "fileSize": 0,
          "isGif": true,
          "isSticker": true,
          "isVoiceNote": true,
          "mimeType": "mimeType",
          "posterImg": "posterImg",
          "size": {
            "height": 0,
            "width": 0
          },
          "srcURL": "srcURL"
        }
      ],
      "isSender": false,
      "isUnread": false,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?"
    }
  ]
}