Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

Retrieve chat details

$client->chats->retrieve(string chatID, ?int maxParticipantCount): Chat
GET/v1/chats/{chatID}

Retrieve chat details, including metadata, participants, and the latest message.

ParametersExpand Collapse
chatID: string

Chat ID. Input routes also accept the local chat ID from this installation when available.

maxParticipantCount?:optional int

Maximum number of participants to return. Use -1 for all; otherwise 0-500. Defaults to 100. List and search endpoints return up to 20 participants per chat.

ReturnsExpand Collapse
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.

Retrieve chat details

<?php

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

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

$chat = $client->chats->retrieve(
  '!NCdzlIaMjZUmvmvyHU:beeper.com', maxParticipantCount: 100
);

var_dump($chat);
{
  "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
}
Returns Examples
{
  "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
}