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, ?int limit): 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.

limit?:optional int

Set the maximum number of chats to retrieve. Valid range: 1-200, default is 25

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.

?ChatCapabilities capabilities

Chat capabilities reported by the platform.

?string description

Group chat description/topic when available.

?ChatDraft 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.

?list<Label> labels

Labels applied to this chat. Absent when the chat has none, or when labels are not enabled for this user.

?\Datetime lastActivity

Timestamp of last activity.

?string lastReadMessageSortKey

Last read message sortKey.

?string localChatID

Local chat ID specific to this installation.

?Merge merge

Present when this chat is a merged chat: one person whose conversations across networks (or across accounts on the same network) are grouped into a single chat. A merged chat holds no messages of its own - read messages from the member chats, and send either to a member directly or to the merged chat ID to route automatically.

?string mergedIntoChatID

When this chat is a member of a merged chat, the ID of that merged chat. Clients that render merged chats as one conversation should list the merged chat and hide chats carrying this field.

?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

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',
  limit: 1,
);

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,
      "labels": [
        {
          "id": "id",
          "name": "name"
        }
      ],
      "lastActivity": "2026-05-05T20:11:54.000Z",
      "lastReadMessageSortKey": "455171049984",
      "localChatID": "5639",
      "merge": {
        "chatIDs": [
          "!NCdzlIaMjZUmvmvyHU:beeper.com"
        ],
        "defaultChatID": "!NCdzlIaMjZUmvmvyHU:beeper.com"
      },
      "mergedIntoChatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
      "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,
      "labels": [
        {
          "id": "id",
          "name": "name"
        }
      ],
      "lastActivity": "2026-05-05T20:11:54.000Z",
      "lastReadMessageSortKey": "455171049984",
      "localChatID": "5639",
      "merge": {
        "chatIDs": [
          "!NCdzlIaMjZUmvmvyHU:beeper.com"
        ],
        "defaultChatID": "!NCdzlIaMjZUmvmvyHU:beeper.com"
      },
      "mergedIntoChatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
      "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"
}