Skip to content
Beeper Developer Docs
  • Auto
  • Light
  • Dark
Download Beeper

List

API Reference
Chats
List chats
client.Chats.List(ctx, query) (*CursorList[ChatListResponse], error)
get/v1/chats

List all chats sorted by last activity (most recent first). Combines all accounts into a single paginated list.

ParametersExpand Collapse
query ChatListParams
AccountIDs param.Field[[]string]optional

Limit to specific account IDs. If omitted, fetches from all accounts.

Cursor param.Field[string]optional

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

Direction param.Field[ChatListParamsDirection]optional

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

const ChatListParamsDirectionAfter ChatListParamsDirection = "after"
const ChatListParamsDirectionBefore ChatListParamsDirection = "before"
ReturnsExpand Collapse
type ChatListResponse struct{…}
Preview Messageoptional

Last message preview for this chat, if available.

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 chats
  • 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.Chats.List(context.TODO(), beeperdesktopapi.ChatListParams{

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

{
  "hasMore": true,
  "items": [
    {
      "id": "!instagram_mattwondra:local-instagram.localhost",
      "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
      "network": "Instagram",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@mattwondra:local-instagram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Matt Wondra",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "mattwondra"
          },
          {
            "id": "@batuhan:local-instagram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "batuhan"
          }
        ],
        "total": 2
      },
      "title": "Matt Wondra",
      "type": "single",
      "unreadCount": 0,
      "isArchived": false,
      "isMuted": false,
      "isPinned": false,
      "lastActivity": "2025-08-31T19:41:41.000Z",
      "lastReadMessageSortKey": 449706228480,
      "localChatID": "1229391",
      "preview": {
        "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?"
      }
    }
  ],
  "newestCursor": "1725489123456",
  "oldestCursor": "1725489123456"
}
Returns Examples
{
  "hasMore": true,
  "items": [
    {
      "id": "!instagram_mattwondra:local-instagram.localhost",
      "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
      "network": "Instagram",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@mattwondra:local-instagram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Matt Wondra",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "mattwondra"
          },
          {
            "id": "@batuhan:local-instagram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "batuhan"
          }
        ],
        "total": 2
      },
      "title": "Matt Wondra",
      "type": "single",
      "unreadCount": 0,
      "isArchived": false,
      "isMuted": false,
      "isPinned": false,
      "lastActivity": "2025-08-31T19:41:41.000Z",
      "lastReadMessageSortKey": 449706228480,
      "localChatID": "1229391",
      "preview": {
        "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?"
      }
    }
  ],
  "newestCursor": "1725489123456",
  "oldestCursor": "1725489123456"
}