List

API Reference

Messages

List messages

client.Messages.List(ctx, chatID, query) (*CursorList[Message], error)

get/v1/chats/{chatID}/messages

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

ParametersExpand Collapse

chatID string

Unique identifier of the chat.

query MessageListParams

Cursor param.Field[string]optional

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

Direction param.Field[MessageListParamsDirection]optional

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

const MessageListParamsDirectionAfter MessageListParamsDirection = "after"

const MessageListParamsDirectionBefore MessageListParamsDirection = "before"

ReturnsExpand Collapse

type Message struct{…}

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 key used to sort messages

Timestamp Time

Message timestamp.

formatdate-time

Attachments []Attachmentoptional

Attachments included with this message, if any.

Type AttachmentType

Attachment type.

Accepts one of the following:

const AttachmentTypeUnknown AttachmentType = "unknown"

const AttachmentTypeImg AttachmentType = "img"

const AttachmentTypeVideo AttachmentType = "video"

const AttachmentTypeAudio AttachmentType = "audio"

Duration float64optional

Duration in seconds (audio/video).

FileName stringoptional

Original filename if available.

FileSize float64optional

File size in bytes if known.

IsGif booloptional

True if the attachment is a GIF.

IsSticker booloptional

True if the attachment is a sticker.

IsVoiceNote booloptional

True if the attachment is a voice note.

MimeType stringoptional

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

PosterImg stringoptional

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 AttachmentSizeoptional

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

Height float64optional

Width float64optional

SrcURL stringoptional

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 booloptional

True if the authenticated user sent the message.

IsUnread booloptional

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

Reactions []Reactionoptional

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 booloptional

True if the reactionKey is an emoji.

ImgURL stringoptional

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

SenderName stringoptional

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

Text stringoptional

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

List messages

package main

import (
  "context"
  "fmt"

  "github.com/beeper/desktop-api-go"
  "github.com/beeper/desktop-api-go/option"
)

func main() {
  client := beeperdesktopapi.NewClient(
    option.WithAccessToken("My Access Token"),
  )
  page, err := client.Messages.List(
    context.TODO(),
    "!NCdzlIaMjZUmvmvyHU:beeper.com",
    beeperdesktopapi.MessageListParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "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?"
    }
  ]
}