List messages

client.messages.list(, ?, ?): CursorNoLimit<Message { id, accountID, chatID, 18 more } >

GET/v1/chats/{chatID}/messages

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

ParametersExpand Collapse

chatID: string

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

query: MessageListParams { cursor, direction }

cursor?: string

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

direction?: "after" | "before"

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

One of the following:

"after"

"before"

ReturnsExpand Collapse

Message { 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.

formatdate-time

attachments?: Array<Attachment { type, id, duration, 10 more } >

Attachments included with this message, if any.

type: "unknown" | "img" | "video" | "audio"

Attachment type.

One of the following:

"unknown"

"img"

"video"

"audio"

id?: string

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

duration?: number

Duration in seconds (audio/video).

fileName?: string

Original filename if available.

fileSize?: number

File size in bytes if known.

isGif?: boolean

True if the attachment is a GIF.

isSticker?: boolean

True if the attachment is a sticker.

isVoiceNote?: boolean

True if the attachment is a voice note.

mimeType?: string

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

posterImg?: 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?: Size { height, width }

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

height?: number

width?: number

srcURL?: 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?: Transcription { engine, transcription, language }

Attachment transcription if available.

engine: string

Transcription engine.

transcription: string

Transcribed text.

language?: string

Detected or selected language.

editedTimestamp?: string

Timestamp when the message was edited, if known.

formatdate-time

isDeleted?: boolean

True if the message has been deleted.

isHidden?: boolean

True if the message is hidden from normal display.

isSender?: boolean

True if the authenticated user sent the message.

isUnread?: boolean

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

linkedMessageID?: string

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

links?: Array<Link>

Link previews included with this message, if any.

title: string

Link preview title.

url: string

Resolved link URL.

favicon?: string

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

img?: string

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

imgSize?: ImgSize { height, width }

Preview image dimensions.

height?: number

width?: number

originalURL?: string

Original URL when the displayed URL is shortened or redirected.

summary?: string

Link preview summary.

mentions?: Array<string> | null

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

reactions?: Array<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?: boolean

True if the reactionKey is an emoji.

imgURL?: string

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

seen?: boolean | string | Record<string, boolean | string>

Read receipt state for this message, when available.

One of the following:

boolean

string

Record<string, boolean | string>

boolean

string

senderName?: string

Resolved sender display name.

sendStatus?: SendStatus { status, timestamp, deliveredToUsers, 3 more }

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

status: "SUCCESS" | "PENDING" | "FAIL_RETRIABLE" | "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?: Array<string>

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

internalError?: string

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

message?: string

Human-readable send status or failure message.

reason?: string

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

text?: string

Rich-text message body if present.

type?: "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"

List messages

import BeeperDesktop from '@beeper/desktop-api';

const client = new BeeperDesktop({
  accessToken: process.env['BEEPER_ACCESS_TOKEN'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const message of client.messages.list('!NCdzlIaMjZUmvmvyHU:beeper.com')) {
  console.log(message.id);
}

{
  "hasMore": true,
  "items": [
    {
      "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"
    }
  ],
  "newestCursor": "newestCursor",
  "oldestCursor": "oldestCursor"
}

Returns Examples

{
  "hasMore": true,
  "items": [
    {
      "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"
    }
  ],
  "newestCursor": "newestCursor",
  "oldestCursor": "oldestCursor"
}

List messages

ParametersExpand Collapse

ReturnsExpand Collapse

List messages

Returns Examples

What can I help you with?