Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

List chats

client.Chats.List(ctx, query) (*CursorNoLimit[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{…}

Chat with optional last message preview.

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

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 Time

Message timestamp.

formatdate-time
Attachments []AttachmentOptional

Attachments included with this message, if any.

Type AttachmentType

Attachment type.

One of the following:
const AttachmentTypeUnknown AttachmentType = "unknown"
const AttachmentTypeImg AttachmentType = "img"
const AttachmentTypeVideo AttachmentType = "video"
const AttachmentTypeAudio AttachmentType = "audio"
ID stringOptional

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

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 available only on 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 file. May be temporary or available only on this device; download promptly if durable access is needed.

Transcription AttachmentTranscriptionOptional

Attachment transcription if available.

Engine string

Transcription engine.

Transcription string

Transcribed text.

Language stringOptional

Detected or selected language.

EditedTimestamp TimeOptional

Timestamp when the message was edited, if known.

formatdate-time
IsDeleted boolOptional

True if the message has been deleted.

IsHidden boolOptional

True if the message is hidden from normal display.

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.

LinkedMessageID stringOptional

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

Mentions []stringOptional

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

Reactions []ReactionOptional

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 boolOptional

True if the reactionKey is an emoji.

ImgURL stringOptional

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

Seen MessageSeenUnionOptional

Read receipt state for this message, when available.

One of the following:
bool
Time
type MessageSeenByParticipant map[string, MessageSeenByParticipantItemUnion]

Group read receipt state keyed by participant ID.

One of the following:
bool
Time
SenderName stringOptional

Resolved sender display name.

SendStatus MessageSendStatusOptional

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

Status string

Current status of the message send attempt.

One of the following:
const MessageSendStatusStatusSuccess MessageSendStatusStatus = "SUCCESS"
const MessageSendStatusStatusPending MessageSendStatusStatus = "PENDING"
const MessageSendStatusStatusFailRetriable MessageSendStatusStatus = "FAIL_RETRIABLE"
const MessageSendStatusStatusFailPermanent MessageSendStatusStatus = "FAIL_PERMANENT"
Timestamp Time

Timestamp for the send status event.

formatdate-time
DeliveredToUsers []stringOptional

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

InternalError stringOptional

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

Message stringOptional

Human-readable send status or failure message.

Reason stringOptional

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

Text stringOptional

Rich-text message body if present.

Type MessageTypeOptional

Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

One of the following:
const MessageTypeText MessageType = "TEXT"
const MessageTypeNotice MessageType = "NOTICE"
const MessageTypeImage MessageType = "IMAGE"
const MessageTypeVideo MessageType = "VIDEO"
const MessageTypeVoice MessageType = "VOICE"
const MessageTypeAudio MessageType = "AUDIO"
const MessageTypeFile MessageType = "FILE"
const MessageTypeSticker MessageType = "STICKER"
const MessageTypeLocation MessageType = "LOCATION"
const MessageTypeReaction MessageType = "REACTION"

List chats

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": "!whatsapp_15550101002:ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc.local-whatsapp.localhost",
      "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
      "network": "WhatsApp",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@15550101002:local-whatsapp.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Kishan Bagaria",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "+15550101002",
            "username": "username",
            "isAdmin": true,
            "isNetworkBot": true,
            "isPending": true
          },
          {
            "id": "@ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc:local-whatsapp.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "username",
            "isAdmin": true,
            "isNetworkBot": true,
            "isPending": true
          }
        ],
        "total": 2
      },
      "title": "Kishan Bagaria",
      "type": "single",
      "unreadCount": 0,
      "capabilities": {
        "allowedReactions": [
          "string"
        ],
        "archive": true,
        "attachments": {
          "foo": {
            "mimeTypes": {
              "foo": -2
            },
            "caption": -2,
            "maxCaptionLength": 0,
            "maxDuration": 0,
            "maxHeight": 0,
            "maxSize": 0,
            "maxWidth": 0,
            "viewOnce": true
          }
        },
        "customEmojiReactions": true,
        "delete": -2,
        "deleteChat": true,
        "deleteChatForEveryone": true,
        "deleteForMe": true,
        "deleteMaxAge": 0,
        "disappearingTimer": {
          "omitEmptyTimer": true,
          "timers": [
            0
          ],
          "types": [
            "afterRead"
          ]
        },
        "edit": -2,
        "editMaxAge": 0,
        "editMaxCount": 0,
        "formatting": {
          "foo": -2
        },
        "locationMessage": -2,
        "markAsUnread": true,
        "maxTextLength": 0,
        "messageRequest": {
          "acceptWithButton": -2,
          "acceptWithMessage": -2
        },
        "participantActions": {
          "ban": -2,
          "invite": -2,
          "kick": -2,
          "leave": -2,
          "revokeInvite": -2
        },
        "poll": -2,
        "reaction": -2,
        "reactionCount": 0,
        "readReceipts": true,
        "reply": -2,
        "state": {
          "avatar": {
            "level": -2
          },
          "description": {
            "level": -2
          },
          "disappearingTimer": {
            "level": -2
          },
          "title": {
            "level": -2
          }
        },
        "thread": -2,
        "typingNotifications": true
      },
      "description": "description",
      "draft": {
        "text": "text",
        "attachments": {
          "foo": {
            "id": "id",
            "type": "file",
            "audioDurationSeconds": 0,
            "fileName": "fileName",
            "filePath": "filePath",
            "fileSize": 0,
            "mimeType": "mimeType",
            "size": {
              "height": 0,
              "width": 0
            },
            "stickerID": "stickerID"
          }
        }
      },
      "imgURL": "imgURL",
      "isArchived": false,
      "isLowPriority": true,
      "isMarkedUnread": true,
      "isMuted": false,
      "isPinned": false,
      "isReadOnly": true,
      "lastActivity": "2026-05-05T20:11:54.000Z",
      "lastReadMessageSortKey": "455171049984",
      "localChatID": "5639",
      "messageExpirySeconds": 0,
      "reminder": {
        "dismissOnIncomingMessage": true,
        "remindAt": "2025-08-31T23:30:12.520Z"
      },
      "snooze": {
        "snoozeUntil": "2025-08-31T23:30:12.520Z",
        "userSnoozedAt": "2025-08-31T23:30:12.520Z"
      },
      "unreadMentionsCount": 0,
      "preview": {
        "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": "1725489123456",
  "oldestCursor": "1725489123456"
}
Returns Examples
{
  "hasMore": true,
  "items": [
    {
      "id": "!whatsapp_15550101002:ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc.local-whatsapp.localhost",
      "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
      "network": "WhatsApp",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@15550101002:local-whatsapp.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Kishan Bagaria",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "+15550101002",
            "username": "username",
            "isAdmin": true,
            "isNetworkBot": true,
            "isPending": true
          },
          {
            "id": "@ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc:local-whatsapp.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "username",
            "isAdmin": true,
            "isNetworkBot": true,
            "isPending": true
          }
        ],
        "total": 2
      },
      "title": "Kishan Bagaria",
      "type": "single",
      "unreadCount": 0,
      "capabilities": {
        "allowedReactions": [
          "string"
        ],
        "archive": true,
        "attachments": {
          "foo": {
            "mimeTypes": {
              "foo": -2
            },
            "caption": -2,
            "maxCaptionLength": 0,
            "maxDuration": 0,
            "maxHeight": 0,
            "maxSize": 0,
            "maxWidth": 0,
            "viewOnce": true
          }
        },
        "customEmojiReactions": true,
        "delete": -2,
        "deleteChat": true,
        "deleteChatForEveryone": true,
        "deleteForMe": true,
        "deleteMaxAge": 0,
        "disappearingTimer": {
          "omitEmptyTimer": true,
          "timers": [
            0
          ],
          "types": [
            "afterRead"
          ]
        },
        "edit": -2,
        "editMaxAge": 0,
        "editMaxCount": 0,
        "formatting": {
          "foo": -2
        },
        "locationMessage": -2,
        "markAsUnread": true,
        "maxTextLength": 0,
        "messageRequest": {
          "acceptWithButton": -2,
          "acceptWithMessage": -2
        },
        "participantActions": {
          "ban": -2,
          "invite": -2,
          "kick": -2,
          "leave": -2,
          "revokeInvite": -2
        },
        "poll": -2,
        "reaction": -2,
        "reactionCount": 0,
        "readReceipts": true,
        "reply": -2,
        "state": {
          "avatar": {
            "level": -2
          },
          "description": {
            "level": -2
          },
          "disappearingTimer": {
            "level": -2
          },
          "title": {
            "level": -2
          }
        },
        "thread": -2,
        "typingNotifications": true
      },
      "description": "description",
      "draft": {
        "text": "text",
        "attachments": {
          "foo": {
            "id": "id",
            "type": "file",
            "audioDurationSeconds": 0,
            "fileName": "fileName",
            "filePath": "filePath",
            "fileSize": 0,
            "mimeType": "mimeType",
            "size": {
              "height": 0,
              "width": 0
            },
            "stickerID": "stickerID"
          }
        }
      },
      "imgURL": "imgURL",
      "isArchived": false,
      "isLowPriority": true,
      "isMarkedUnread": true,
      "isMuted": false,
      "isPinned": false,
      "isReadOnly": true,
      "lastActivity": "2026-05-05T20:11:54.000Z",
      "lastReadMessageSortKey": "455171049984",
      "localChatID": "5639",
      "messageExpirySeconds": 0,
      "reminder": {
        "dismissOnIncomingMessage": true,
        "remindAt": "2025-08-31T23:30:12.520Z"
      },
      "snooze": {
        "snoozeUntil": "2025-08-31T23:30:12.520Z",
        "userSnoozedAt": "2025-08-31T23:30:12.520Z"
      },
      "unreadMentionsCount": 0,
      "preview": {
        "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": "1725489123456",
  "oldestCursor": "1725489123456"
}