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

List

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.

Accepts 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, 10 more }

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

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

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

Message timestamp.

formatdate-time
attachments: optional array of Attachment { type, duration, fileName, 8 more }

Attachments included with this message, if any.

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

Attachment type.

Accepts one of the following:
"unknown"
"img"
"video"
"audio"
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 local-only to 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 asset. May be temporary or local-only to this device; download promptly if durable access is needed.

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.

reactions: optional array of Reaction { id, participantID, reactionKey, 2 more }

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: optional boolean

True if the reactionKey is an emoji.

imgURL: optional string

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

senderName: optional string

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

text: optional string

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

newestCursor: string

Timestamp cursor (ms since epoch) for fetching newer results (use with direction='after').

oldestCursor: string

Timestamp cursor (ms since epoch) for fetching older results (use with direction='before').

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