List messages

$ beeper-desktop-cli messages list

GET/v1/chats/{chatID}/messages

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

ParametersExpand Collapse

--chat-id: string

Unique identifier of the chat.

--cursor: optional string

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

--direction: optional "after" or "before"

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

ReturnsExpand Collapse

ListMessagesOutput: object { hasMore, items }

hasMore: boolean

True if additional results can be fetched.

items: array of Message { id, accountID, chatID, 11 more }

Messages from the chat, sorted by timestamp. Use message.sortKey as the cursor for pagination and treat it as an opaque value.

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.

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.

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

"TEXT"

"NOTICE"

"IMAGE"

"VIDEO"

"VOICE"

"AUDIO"

"FILE"

"STICKER"

"LOCATION"

"REACTION"

List messages

beeper-desktop-cli messages list \
  --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com'

{
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": "aaaa1",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "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"
        }
      ],
      "isSender": false,
      "isUnread": false,
      "linkedMessageID": "linkedMessageID",
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?",
      "type": "TEXT"
    }
  ]
}

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": "aaaa1",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "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"
        }
      ],
      "isSender": false,
      "isUnread": false,
      "linkedMessageID": "linkedMessageID",
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?",
      "type": "TEXT"
    }
  ]
}