API Reference

Messages

Search messages

client.Messages.Search(ctx, query) (*CursorSearch[Message], error)

get/v1/messages/search

Search messages across chats using Beeper's message index

ParametersExpand Collapse

query MessageSearchParams

AccountIDs param.Field[[]string]optional

Limit search to specific account IDs.

ChatIDs param.Field[[]string]optional

Limit search to specific chat IDs.

ChatType param.Field[MessageSearchParamsChatType]optional

Filter by chat type: 'group' for group chats, 'single' for 1:1 chats.

const MessageSearchParamsChatTypeGroup MessageSearchParamsChatType = "group"

const MessageSearchParamsChatTypeSingle MessageSearchParamsChatType = "single"

Cursor param.Field[string]optional

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

DateAfter param.Field[Time]optional

Only include messages with timestamp strictly after this ISO 8601 datetime (e.g., '2024-07-01T00:00:00Z' or '2024-07-01T00:00:00+02:00').

formatdate-time

DateBefore param.Field[Time]optional

Only include messages with timestamp strictly before this ISO 8601 datetime (e.g., '2024-07-31T23:59:59Z' or '2024-07-31T23:59:59+02:00').

formatdate-time

Direction param.Field[MessageSearchParamsDirection]optional

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

const MessageSearchParamsDirectionAfter MessageSearchParamsDirection = "after"

const MessageSearchParamsDirectionBefore MessageSearchParamsDirection = "before"

ExcludeLowPriority param.Field[bool]optional

Exclude messages marked Low Priority by the user. Default: true. Set to false to include all.

IncludeMuted param.Field[bool]optional

Include messages in chats marked as Muted by the user, which are usually less important. Default: true. Set to false if the user wants a more refined search.

Limit param.Field[int64]optional

Maximum number of messages to return.

minimum0

exclusiveMinimum

maximum20

MediaTypes param.Field[[]string]optional

Filter messages by media types. Use ['any'] for any media type, or specify exact types like ['video', 'image']. Omit for no media filtering.

const MessageSearchParamsMediaTypeAny MessageSearchParamsMediaType = "any"

const MessageSearchParamsMediaTypeVideo MessageSearchParamsMediaType = "video"

const MessageSearchParamsMediaTypeImage MessageSearchParamsMediaType = "image"

const MessageSearchParamsMediaTypeLink MessageSearchParamsMediaType = "link"

const MessageSearchParamsMediaTypeFile MessageSearchParamsMediaType = "file"

Query param.Field[string]optional

Literal word search (NOT semantic). Finds messages containing these EXACT words in any order. Use single words users actually type, not concepts or phrases. Example: use "dinner" not "dinner plans", use "sick" not "health issues". If omitted, returns results filtered only by other parameters.

minLength0

Sender param.Field[MessageSearchParamsSender]optional

Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id).

type MessageSearchParamsSender string

Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id).

Accepts one of the following:

const MessageSearchParamsSenderMe MessageSearchParamsSender = "me"

const MessageSearchParamsSenderOthers MessageSearchParamsSender = "others"

string

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, sortable 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.

Search messages

Go

HTTP

TypeScript

Python

Go

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.Search(context.TODO(), beeperdesktopapi.MessageSearchParams{

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

200 example

{
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "network": "Signal",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@adamvy:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Adam Van Ymeren",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "username"
          },
          {
            "id": "@batuhan:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "username"
          }
        ],
        "total": 2
      },
      "type": "single",
      "unreadCount": 0,
      "description": "description",
      "isArchived": false,
      "isMuted": false,
      "isPinned": true,
      "lastActivity": "2025-08-31T17:38:20.393Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229720",
      "title": "Adam Van Ymeren"
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "network": "Telegram",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@nick:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Nick Mills-Barrett",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "nick"
          },
          {
            "id": "@batuhan:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "batuhan"
          }
        ],
        "total": 2
      },
      "type": "single",
      "unreadCount": 2,
      "description": "description",
      "isArchived": false,
      "isMuted": true,
      "isPinned": false,
      "lastActivity": "2025-08-31T16:45:10.123Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229721",
      "title": "Nick Mills-Barrett"
    }
  },
  "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",
          "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?"
    },
    {
      "id": "1343994",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": "aaaa2",
      "timestamp": "2025-08-28T14:22:15.432Z",
      "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": true,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Nick Mills-Barrett",
      "text": "The deployment is complete, everything looks good"
    }
  ],
  "newestCursor": null,
  "oldestCursor": "1756379069621"
}

Returns Examples

200 example

{
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "network": "Signal",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@adamvy:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Adam Van Ymeren",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "username"
          },
          {
            "id": "@batuhan:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "username"
          }
        ],
        "total": 2
      },
      "type": "single",
      "unreadCount": 0,
      "description": "description",
      "isArchived": false,
      "isMuted": false,
      "isPinned": true,
      "lastActivity": "2025-08-31T17:38:20.393Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229720",
      "title": "Adam Van Ymeren"
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "network": "Telegram",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@nick:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Nick Mills-Barrett",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "nick"
          },
          {
            "id": "@batuhan:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "batuhan"
          }
        ],
        "total": 2
      },
      "type": "single",
      "unreadCount": 2,
      "description": "description",
      "isArchived": false,
      "isMuted": true,
      "isPinned": false,
      "lastActivity": "2025-08-31T16:45:10.123Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229721",
      "title": "Nick Mills-Barrett"
    }
  },
  "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",
          "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?"
    },
    {
      "id": "1343994",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": "aaaa2",
      "timestamp": "2025-08-28T14:22:15.432Z",
      "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": true,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Nick Mills-Barrett",
      "text": "The deployment is complete, everything looks good"
    }
  ],
  "newestCursor": null,
  "oldestCursor": "1756379069621"
}