Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

List chats

GET/v1/chats

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

Query ParametersExpand Collapse
accountIDs: optional array of string

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

cursor: optional string

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

direction: optional "after" or "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
hasMore: boolean

True if additional results can be fetched using the provided cursors.

items: array of Chat { id, accountID, network, 21 more }

Chats ordered by last activity timestamp (most recent first).

preview: optional Message { id, accountID, chatID, 18 more }

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: string

Message timestamp.

formatdate-time
attachments: optional array of Attachment { type, id, duration, 10 more }

Attachments included with this message, if any.

type: "unknown" or "img" or "video" or "audio"

Attachment type.

One of the following:
"unknown"
"img"
"video"
"audio"
id: optional string

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

duration: optional number

Duration in seconds (audio/video).

fileName: optional string

Original filename if available.

fileSize: optional number

File size in bytes if known.

isGif: optional boolean

True if the attachment is a GIF.

isSticker: optional boolean

True if the attachment is a sticker.

isVoiceNote: optional boolean

True if the attachment is a voice note.

mimeType: optional string

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

posterImg: optional 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: optional object { height, width }

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

height: optional number
width: optional number
srcURL: optional 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: optional object { engine, transcription, language }

Attachment transcription if available.

engine: string

Transcription engine.

transcription: string

Transcribed text.

language: optional string

Detected or selected language.

editedTimestamp: optional string

Timestamp when the message was edited, if known.

formatdate-time
isDeleted: optional boolean

True if the message has been deleted.

isHidden: optional boolean

True if the message is hidden from normal display.

isSender: optional boolean

True if the authenticated user sent the message.

isUnread: optional boolean

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

linkedMessageID: optional string

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

mentions: optional array of string

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

reactions: optional array of 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: optional boolean

True if the reactionKey is an emoji.

imgURL: optional string

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

seen: optional boolean or string or map[boolean or string]

Read receipt state for this message, when available.

One of the following:
Boolean = boolean
Timestamp = string

ISO 8601 timestamp.

ByParticipant = map[boolean or string]

Group read receipt state keyed by participant ID.

One of the following:
Boolean = boolean
Timestamp = string

ISO 8601 timestamp.

senderName: optional string

Resolved sender display name.

sendStatus: optional object { status, timestamp, deliveredToUsers, 3 more }

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

status: "SUCCESS" or "PENDING" or "FAIL_RETRIABLE" or "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: optional array of string

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

internalError: optional string

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

message: optional string

Human-readable send status or failure message.

reason: optional string

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

text: optional string

Rich-text message body if present.

type: optional "TEXT" or "NOTICE" or "IMAGE" or 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"
newestCursor: string

Cursor for fetching newer results (use with direction=‘after’). Opaque string; do not inspect.

oldestCursor: string

Cursor for fetching older results (use with direction=‘before’). Opaque string; do not inspect.

List chats

curl http://localhost:23373/v1/chats \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN"
{
  "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"
}