# Chats

## Retrieve

`$client->chats->retrieve(string chatID, ?int maxParticipantCount): Chat`

**get** `/v1/chats/{chatID}`

Retrieve chat details including metadata, participants, and latest message

### Parameters

- `chatID: string`

  Unique identifier of the chat.

- `maxParticipantCount?:optional int`

  Maximum number of participants to return. Use -1 for all; otherwise 0–500. Defaults to all (-1).

### Returns

- `Chat`

  - `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.

### Example

```php
<?php

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

$client = new Client();

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

var_dump($chat);
```

## Create

`$client->chats->create(string accountID, ?bool allowInvite, ?string messageText, ?Mode mode, ?list<string> participantIDs, ?string title, ?Type type, ?User user): ChatNewResponse`

**post** `/v1/chats`

Create a single/group chat (mode='create') or start a direct chat from merged user data (mode='start').

### Parameters

- `accountID: string`

  Account to create or start the chat on.

- `allowInvite?:optional bool`

  Whether invite-based DM creation is allowed when required by the platform. Used for mode='start'.

- `messageText?:optional string`

  Optional first message content if the platform requires it to create the chat.

- `mode?:optional Mode`

  Operation mode. Defaults to 'create' when omitted.

- `participantIDs?:optional list<string>`

  Required when mode='create'. User IDs to include in the new chat.

- `title?:optional string`

  Optional title for group chats when mode='create'; ignored for single chats on most platforms.

- `type?:optional Type`

  Required when mode='create'. 'single' requires exactly one participantID; 'group' supports multiple participants and optional title.

- `user?:optional User`

  Required when mode='start'. Merged user-like contact payload used to resolve the best identifier.

### Returns

- `ChatNewResponse`

  - `string chatID`

    Newly created chat ID.

  - `?Status status`

    Only returned in start mode. 'existing' means an existing chat was reused; 'created' means a new chat was created.

### Example

```php
<?php

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

$client = new Client();

$chat = $client->chats->create(
  accountID: 'accountID',
  allowInvite: true,
  messageText: 'messageText',
  mode: 'create',
  participantIDs: ['string'],
  title: 'title',
  type: 'single',
  user: [
    'id' => 'id',
    'email' => 'email',
    'fullName' => 'fullName',
    'phoneNumber' => 'phoneNumber',
    'username' => 'username',
  ],
);

var_dump($chat);
```

## List

`$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.

### Parameters

- `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.

### Returns

- `ChatListResponse`

  - `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`

### Example

```php
<?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);
```

## Search

`$client->chats->search(?list<string> accountIDs, ?string cursor, ?Direction direction, ?Inbox inbox, ?bool includeMuted, ?\Datetime lastActivityAfter, ?\Datetime lastActivityBefore, ?int limit, ?string query, ?Scope scope, ?Type type, ?bool unreadOnly): CursorSearch<Chat>`

**get** `/v1/chats/search`

Search chats by title/network or participants using Beeper Desktop's renderer algorithm.

### Parameters

- `accountIDs?:optional list<string>`

  Provide an array of account IDs to filter chats from specific messaging accounts only

- `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.

- `inbox?:optional Inbox`

  Filter by inbox type: "primary" (non-archived, non-low-priority), "low-priority", or "archive". If not specified, shows all chats.

- `includeMuted?:optional bool`

  Include chats marked as Muted by the user, which are usually less important. Default: true. Set to false if the user wants a more refined search.

- `lastActivityAfter?:optional \Datetime`

  Provide an ISO datetime string to only retrieve chats with last activity after this time

- `lastActivityBefore?:optional \Datetime`

  Provide an ISO datetime string to only retrieve chats with last activity before this time

- `limit?:optional int`

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

- `query?:optional string`

  Literal token search (non-semantic). Use single words users type (e.g., "dinner"). When multiple words provided, ALL must match. Case-insensitive.

- `scope?:optional Scope`

  Search scope: 'titles' matches title + network; 'participants' matches participant names.

- `type?:optional Type`

  Specify the type of chats to retrieve: use "single" for direct messages, "group" for group chats, or "any" to get all types

- `unreadOnly?:optional bool`

  Set to true to only retrieve chats that have unread messages

### Returns

- `Chat`

  - `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.

### Example

```php
<?php

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

$client = new Client();

$page = $client->chats->search(
  accountIDs: [
    'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc',
    'local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI',
  ],
  cursor: '1725489123456|c29tZUltc2dQYWdl',
  direction: 'before',
  inbox: 'primary',
  includeMuted: true,
  lastActivityAfter: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'),
  lastActivityBefore: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'),
  limit: 1,
  query: 'x',
  scope: 'titles',
  type: 'single',
  unreadOnly: true,
);

var_dump($page);
```

## Archive

`$client->chats->archive(string chatID, ?bool archived): void`

**post** `/v1/chats/{chatID}/archive`

Archive or unarchive a chat. Set archived=true to move to archive, archived=false to move back to inbox

### Parameters

- `chatID: string`

  Unique identifier of the chat.

- `archived?:optional bool`

  True to archive, false to unarchive

### Example

```php
<?php

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

$client = new Client();

$result = $client->chats->archive(
  '!NCdzlIaMjZUmvmvyHU:beeper.com', archived: true
);

var_dump($result);
```

## Domain Types

### Chat

- `Chat`

  - `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.

# Reminders

## Create

`$client->chats->reminders->create(string chatID, Reminder reminder): void`

**post** `/v1/chats/{chatID}/reminders`

Set a reminder for a chat at a specific time

### Parameters

- `chatID: string`

  Unique identifier of the chat.

- `reminder: Reminder`

  Reminder configuration

### Example

```php
<?php

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

$client = new Client();

$result = $client->chats->reminders->create(
  '!NCdzlIaMjZUmvmvyHU:beeper.com',
  reminder: ['remindAtMs' => 0, 'dismissOnIncomingMessage' => true],
);

var_dump($result);
```

## Delete

`$client->chats->reminders->delete(string chatID): void`

**delete** `/v1/chats/{chatID}/reminders`

Clear an existing reminder from a chat

### Parameters

- `chatID: string`

  Unique identifier of the chat.

### Example

```php
<?php

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

$client = new Client();

$result = $client->chats->reminders->delete('!NCdzlIaMjZUmvmvyHU:beeper.com');

var_dump($result);
```

# Messages

# Reactions

## Add

`$client->chats->messages->reactions->add(string messageID, string chatID, string reactionKey, ?string transactionID): ReactionAddResponse`

**post** `/v1/chats/{chatID}/messages/{messageID}/reactions`

Add a reaction to an existing message.

### Parameters

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

- `reactionKey: string`

  Reaction key to add (emoji, shortcode, or custom emoji key)

- `transactionID?:optional string`

  Optional transaction ID for deduplication and local echo tracking

### Returns

- `ReactionAddResponse`

  - `string chatID`

    Unique identifier of the chat.

  - `string messageID`

    Message ID.

  - `string reactionKey`

    Reaction key that was added

  - `true success`

    Whether the reaction was successfully added

  - `string transactionID`

    Transaction ID used for the reaction event

### Example

```php
<?php

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

$client = new Client();

$response = $client->chats->messages->reactions->add(
  'messageID',
  chatID: '!NCdzlIaMjZUmvmvyHU:beeper.com',
  reactionKey: 'x',
  transactionID: 'transactionID',
);

var_dump($response);
```

## Delete

`$client->chats->messages->reactions->delete(string messageID, string chatID, string reactionKey): ReactionDeleteResponse`

**delete** `/v1/chats/{chatID}/messages/{messageID}/reactions`

Remove the authenticated user's reaction from an existing message.

### Parameters

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

- `reactionKey: string`

  Reaction key to remove

### Returns

- `ReactionDeleteResponse`

  - `string chatID`

    Unique identifier of the chat.

  - `string messageID`

    Message ID.

  - `string reactionKey`

    Reaction key that was removed

  - `true success`

    Whether the reaction was successfully removed

### Example

```php
<?php

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

$client = new Client();

$reaction = $client->chats->messages->reactions->delete(
  'messageID', chatID: '!NCdzlIaMjZUmvmvyHU:beeper.com', reactionKey: 'x'
);

var_dump($reaction);
```