Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

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

Unique identifier of the chat across Beeper.

string accountID

Account ID this chat belongs to.

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.

?bool isArchived

True if chat is archived.

?bool isMuted

True if chat notifications are muted.

?bool isPinned

True if chat is pinned.

?\Datetime lastActivity

Timestamp of last activity.

?string lastReadMessageSortKey

Last read message sortKey.

?string localChatID

Local chat ID specific to this Beeper Desktop installation.

?Message preview

List chats

<?php

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

$client = new Client();

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

var_dump($page);
{
  "hasMore": true,
  "items": [
    {
      "id": "!instagram_mattwondra:local-instagram.localhost",
      "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
      "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": "aaaa1",
        "timestamp": "2025-08-28T11:04:29.621Z",
        "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"
          }
        ],
        "isSender": false,
        "isUnread": false,
        "linkedMessageID": "linkedMessageID",
        "reactions": [
          {
            "id": "id",
            "participantID": "participantID",
            "reactionKey": "reactionKey",
            "emoji": true,
            "imgURL": "imgURL"
          }
        ],
        "senderName": "Adam Van Ymeren",
        "text": "Hey, can we reschedule our meeting to 3pm?",
        "type": "TEXT"
      }
    }
  ],
  "newestCursor": "1725489123456",
  "oldestCursor": "1725489123456"
}
Returns Examples
{
  "hasMore": true,
  "items": [
    {
      "id": "!instagram_mattwondra:local-instagram.localhost",
      "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
      "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": "aaaa1",
        "timestamp": "2025-08-28T11:04:29.621Z",
        "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"
          }
        ],
        "isSender": false,
        "isUnread": false,
        "linkedMessageID": "linkedMessageID",
        "reactions": [
          {
            "id": "id",
            "participantID": "participantID",
            "reactionKey": "reactionKey",
            "emoji": true,
            "imgURL": "imgURL"
          }
        ],
        "senderName": "Adam Van Ymeren",
        "text": "Hey, can we reschedule our meeting to 3pm?",
        "type": "TEXT"
      }
    }
  ],
  "newestCursor": "1725489123456",
  "oldestCursor": "1725489123456"
}