API Reference

Chats

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List chats

$client->chats->list(?list<string> accountIDs, ?string cursor, ?Direction direction): CursorNoLimit<ChatListResponse>

GET/v1/chats

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

ParametersExpand Collapse

accountIDs?:optional list<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 Direction

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

ReturnsExpand Collapse

ChatListResponse

string id

Unique identifier of the chat across Beeper.

string accountID

Account ID this chat belongs to.

string network

Display-only human-readable account/network name.

Participants participants

Chat participants information.

string title

Display title of the chat as computed by the client/server.

Type type

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

int unreadCount

Number of unread messages.

?Capabilities capabilities

Chat capabilities reported by the platform.

?string description

Group chat description/topic when available.

?Draft draft

Current draft object for this chat, or null when no draft is set.

?string imgURL

Local filesystem path to the chat avatar image when available.

?bool isArchived

True if chat is archived.

?bool isLowPriority

True if chat is marked low priority.

?bool isMarkedUnread

True if the chat was explicitly marked unread by the authenticated user.

?bool isMuted

True if chat notifications are muted.

?bool isPinned

True if chat is pinned.

?bool isReadOnly

True if messages cannot be sent in this chat.

?\Datetime lastActivity

Timestamp of last activity.

?string lastReadMessageSortKey

Last read message sortKey.

?string localChatID

Local chat ID specific to this installation.

?int messageExpirySeconds

Disappearing-message timer in seconds when available.

?Reminder reminder

Current reminder for this chat, or null when no reminder is set.

?Snooze snooze

Current snooze state for this chat, or null when no snooze is set.

?int unreadMentionsCount

Number of unread messages that mention the authenticated user or @room.

?Message preview

List chats

PHP

HTTP

TypeScript

Python

Go

CLI Tool

PHP

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$page = $client->chats->list(
  accountIDs: [
    'matrix', 'discordgo', 'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc'
  ],
  cursor: '1725489123456|c29tZUltc2dQYWdl',
  direction: 'before',
);

var_dump($page);

200 example

{
  "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

200 example

{
  "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"
}