# Chats

## Retrieve

`chats.retrieve(strchat_id, ChatRetrieveParams**kwargs)  -> Chat`

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

Retrieve chat details including metadata, participants, and latest message

### Parameters

- `chat_id: str`

  Unique identifier of the chat.

- `max_participant_count: Optional[int]`

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

### Returns

- `class Chat: …`

  - `id: str`

    Unique identifier of the chat across Beeper.

  - `account_id: str`

    Account ID this chat belongs to.

  - `participants: Participants`

    Chat participants information.

    - `has_more: bool`

      True if there are more participants than included in items.

    - `items: List[User]`

      Participants returned for this chat (limited by the request; may be a subset).

      - `id: str`

        Stable Beeper user ID. Use as the primary key when referencing a person.

      - `cannot_message: Optional[bool]`

        True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

      - `email: Optional[str]`

        Email address if known. Not guaranteed verified.

      - `full_name: Optional[str]`

        Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

      - `img_url: Optional[str]`

        Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

      - `is_self: Optional[bool]`

        True if this user represents the authenticated account's own identity.

      - `phone_number: Optional[str]`

        User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

      - `username: Optional[str]`

        Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

    - `total: int`

      Total number of participants in the chat.

  - `title: str`

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

  - `type: Literal["single", "group"]`

    Chat type: 'single' for direct messages, 'group' for group chats.

    - `"single"`

    - `"group"`

  - `unread_count: int`

    Number of unread messages.

  - `is_archived: Optional[bool]`

    True if chat is archived.

  - `is_muted: Optional[bool]`

    True if chat notifications are muted.

  - `is_pinned: Optional[bool]`

    True if chat is pinned.

  - `last_activity: Optional[datetime]`

    Timestamp of last activity.

  - `last_read_message_sort_key: Optional[str]`

    Last read message sortKey.

  - `local_chat_id: Optional[str]`

    Local chat ID specific to this Beeper Desktop installation.

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
chat = client.chats.retrieve(
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
)
print(chat.id)
```

## Create

`chats.create(ChatCreateParams**kwargs)  -> ChatCreateResponse`

**post** `/v1/chats`

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

### Parameters

- `account_id: str`

  Account to create or start the chat on.

- `allow_invite: Optional[bool]`

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

- `message_text: Optional[str]`

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

- `mode: Optional[Literal["create", "start"]]`

  Operation mode. Defaults to 'create' when omitted.

  - `"create"`

  - `"start"`

- `participant_ids: Optional[SequenceNotStr[str]]`

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

- `title: Optional[str]`

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

- `type: Optional[Literal["single", "group"]]`

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

  - `"single"`

  - `"group"`

- `user: Optional[User]`

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

  - `id: Optional[str]`

    Known user ID when available.

  - `email: Optional[str]`

    Email candidate.

  - `full_name: Optional[str]`

    Display name hint used for ranking only.

  - `phone_number: Optional[str]`

    Phone number candidate (E.164 preferred).

  - `username: Optional[str]`

    Username/handle candidate.

### Returns

- `class ChatCreateResponse: …`

  - `chat_id: str`

    Newly created chat ID.

  - `status: Optional[Literal["existing", "created"]]`

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

    - `"existing"`

    - `"created"`

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
chat = client.chats.create(
    account_id="accountID",
)
print(chat.chat_id)
```

## List

`chats.list(ChatListParams**kwargs)  -> SyncCursorNoLimit[ChatListResponse]`

**get** `/v1/chats`

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

### Parameters

- `account_ids: Optional[SequenceNotStr[str]]`

  Limit to specific account IDs. If omitted, fetches from all accounts.

- `cursor: Optional[str]`

  Opaque pagination cursor; do not inspect. Use together with 'direction'.

- `direction: Optional[Literal["after", "before"]]`

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

  - `"after"`

  - `"before"`

### Returns

- `class ChatListResponse: …`

  - `preview: Optional[Message]`

    Last message preview for this chat, if available.

    - `id: str`

      Message ID.

    - `account_id: str`

      Beeper account ID the message belongs to.

    - `chat_id: str`

      Unique identifier of the chat.

    - `sender_id: str`

      Sender user ID.

    - `sort_key: str`

      A unique, sortable key used to sort messages.

    - `timestamp: datetime`

      Message timestamp.

    - `attachments: Optional[List[Attachment]]`

      Attachments included with this message, if any.

      - `type: Literal["unknown", "img", "video", "audio"]`

        Attachment type.

        - `"unknown"`

        - `"img"`

        - `"video"`

        - `"audio"`

      - `id: Optional[str]`

        Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path.

      - `duration: Optional[float]`

        Duration in seconds (audio/video).

      - `file_name: Optional[str]`

        Original filename if available.

      - `file_size: Optional[float]`

        File size in bytes if known.

      - `is_gif: Optional[bool]`

        True if the attachment is a GIF.

      - `is_sticker: Optional[bool]`

        True if the attachment is a sticker.

      - `is_voice_note: Optional[bool]`

        True if the attachment is a voice note.

      - `mime_type: Optional[str]`

        MIME type if known (e.g., 'image/png').

      - `poster_img: Optional[str]`

        Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed.

      - `size: Optional[Size]`

        Pixel dimensions of the attachment: width/height in px.

        - `height: Optional[float]`

        - `width: Optional[float]`

      - `src_url: Optional[str]`

        Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed.

    - `is_sender: Optional[bool]`

      True if the authenticated user sent the message.

    - `is_unread: Optional[bool]`

      True if the message is unread for the authenticated user. May be omitted.

    - `linked_message_id: Optional[str]`

      ID of the message this is a reply to, if any.

    - `reactions: Optional[List[Reaction]]`

      Reactions to the message, if any.

      - `id: str`

        Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise.

      - `participant_id: str`

        User ID of the participant who reacted.

      - `reaction_key: str`

        The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face".

      - `emoji: Optional[bool]`

        True if the reactionKey is an emoji.

      - `img_url: Optional[str]`

        URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed.

    - `sender_name: Optional[str]`

      Resolved sender display name (impersonator/full name/username/participant name).

    - `text: Optional[str]`

      Plain-text body if present. May include a JSON fallback with text entities for rich messages.

    - `type: Optional[Literal["TEXT", "NOTICE", "IMAGE", 7 more]]`

      Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

      - `"TEXT"`

      - `"NOTICE"`

      - `"IMAGE"`

      - `"VIDEO"`

      - `"VOICE"`

      - `"AUDIO"`

      - `"FILE"`

      - `"STICKER"`

      - `"LOCATION"`

      - `"REACTION"`

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
page = client.chats.list()
page = page.items[0]
print(page)
```

## Search

`chats.search(ChatSearchParams**kwargs)  -> SyncCursorSearch[Chat]`

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

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

### Parameters

- `account_ids: Optional[SequenceNotStr[str]]`

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

- `cursor: Optional[str]`

  Opaque pagination cursor; do not inspect. Use together with 'direction'.

- `direction: Optional[Literal["after", "before"]]`

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

  - `"after"`

  - `"before"`

- `inbox: Optional[Literal["primary", "low-priority", "archive"]]`

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

  - `"primary"`

  - `"low-priority"`

  - `"archive"`

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

- `last_activity_after: Optional[Union[str, datetime]]`

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

- `last_activity_before: Optional[Union[str, 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[str]`

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

- `scope: Optional[Literal["titles", "participants"]]`

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

  - `"titles"`

  - `"participants"`

- `type: Optional[Literal["single", "group", "any"]]`

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

  - `"single"`

  - `"group"`

  - `"any"`

- `unread_only: Optional[bool]`

  Set to true to only retrieve chats that have unread messages

### Returns

- `class Chat: …`

  - `id: str`

    Unique identifier of the chat across Beeper.

  - `account_id: str`

    Account ID this chat belongs to.

  - `participants: Participants`

    Chat participants information.

    - `has_more: bool`

      True if there are more participants than included in items.

    - `items: List[User]`

      Participants returned for this chat (limited by the request; may be a subset).

      - `id: str`

        Stable Beeper user ID. Use as the primary key when referencing a person.

      - `cannot_message: Optional[bool]`

        True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

      - `email: Optional[str]`

        Email address if known. Not guaranteed verified.

      - `full_name: Optional[str]`

        Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

      - `img_url: Optional[str]`

        Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

      - `is_self: Optional[bool]`

        True if this user represents the authenticated account's own identity.

      - `phone_number: Optional[str]`

        User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

      - `username: Optional[str]`

        Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

    - `total: int`

      Total number of participants in the chat.

  - `title: str`

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

  - `type: Literal["single", "group"]`

    Chat type: 'single' for direct messages, 'group' for group chats.

    - `"single"`

    - `"group"`

  - `unread_count: int`

    Number of unread messages.

  - `is_archived: Optional[bool]`

    True if chat is archived.

  - `is_muted: Optional[bool]`

    True if chat notifications are muted.

  - `is_pinned: Optional[bool]`

    True if chat is pinned.

  - `last_activity: Optional[datetime]`

    Timestamp of last activity.

  - `last_read_message_sort_key: Optional[str]`

    Last read message sortKey.

  - `local_chat_id: Optional[str]`

    Local chat ID specific to this Beeper Desktop installation.

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
page = client.chats.search()
page = page.items[0]
print(page.id)
```

## Archive

`chats.archive(strchat_id, ChatArchiveParams**kwargs)`

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

- `chat_id: str`

  Unique identifier of the chat.

- `archived: Optional[bool]`

  True to archive, false to unarchive

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
client.chats.archive(
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
)
```

## Domain Types

### Chat

- `class Chat: …`

  - `id: str`

    Unique identifier of the chat across Beeper.

  - `account_id: str`

    Account ID this chat belongs to.

  - `participants: Participants`

    Chat participants information.

    - `has_more: bool`

      True if there are more participants than included in items.

    - `items: List[User]`

      Participants returned for this chat (limited by the request; may be a subset).

      - `id: str`

        Stable Beeper user ID. Use as the primary key when referencing a person.

      - `cannot_message: Optional[bool]`

        True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

      - `email: Optional[str]`

        Email address if known. Not guaranteed verified.

      - `full_name: Optional[str]`

        Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

      - `img_url: Optional[str]`

        Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

      - `is_self: Optional[bool]`

        True if this user represents the authenticated account's own identity.

      - `phone_number: Optional[str]`

        User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

      - `username: Optional[str]`

        Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

    - `total: int`

      Total number of participants in the chat.

  - `title: str`

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

  - `type: Literal["single", "group"]`

    Chat type: 'single' for direct messages, 'group' for group chats.

    - `"single"`

    - `"group"`

  - `unread_count: int`

    Number of unread messages.

  - `is_archived: Optional[bool]`

    True if chat is archived.

  - `is_muted: Optional[bool]`

    True if chat notifications are muted.

  - `is_pinned: Optional[bool]`

    True if chat is pinned.

  - `last_activity: Optional[datetime]`

    Timestamp of last activity.

  - `last_read_message_sort_key: Optional[str]`

    Last read message sortKey.

  - `local_chat_id: Optional[str]`

    Local chat ID specific to this Beeper Desktop installation.

# Reminders

## Create

`chats.reminders.create(strchat_id, ReminderCreateParams**kwargs)`

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

Set a reminder for a chat at a specific time

### Parameters

- `chat_id: str`

  Unique identifier of the chat.

- `reminder: Reminder`

  Reminder configuration

  - `remind_at_ms: float`

    Unix timestamp in milliseconds when reminder should trigger

  - `dismiss_on_incoming_message: Optional[bool]`

    Cancel reminder if someone messages in the chat

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
client.chats.reminders.create(
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
    reminder={
        "remind_at_ms": 0
    },
)
```

## Delete

`chats.reminders.delete(strchat_id)`

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

Clear an existing reminder from a chat

### Parameters

- `chat_id: str`

  Unique identifier of the chat.

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
client.chats.reminders.delete(
    "!NCdzlIaMjZUmvmvyHU:beeper.com",
)
```

# Messages

# Reactions

## Add

`chats.messages.reactions.add(strmessage_id, ReactionAddParams**kwargs)  -> ReactionAddResponse`

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

Add a reaction to an existing message.

### Parameters

- `chat_id: str`

  Unique identifier of the chat.

- `message_id: str`

- `reaction_key: str`

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

- `transaction_id: Optional[str]`

  Optional transaction ID for deduplication and local echo tracking

### Returns

- `class ReactionAddResponse: …`

  - `chat_id: str`

    Unique identifier of the chat.

  - `message_id: str`

    Message ID.

  - `reaction_key: str`

    Reaction key that was added

  - `success: Literal[true]`

    Whether the reaction was successfully added

    - `true`

  - `transaction_id: str`

    Transaction ID used for the reaction event

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
response = client.chats.messages.reactions.add(
    message_id="messageID",
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
    reaction_key="x",
)
print(response.chat_id)
```

## Delete

`chats.messages.reactions.delete(strmessage_id, ReactionDeleteParams**kwargs)  -> ReactionDeleteResponse`

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

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

### Parameters

- `chat_id: str`

  Unique identifier of the chat.

- `message_id: str`

- `reaction_key: str`

  Reaction key to remove

### Returns

- `class ReactionDeleteResponse: …`

  - `chat_id: str`

    Unique identifier of the chat.

  - `message_id: str`

    Message ID.

  - `reaction_key: str`

    Reaction key that was removed

  - `success: Literal[true]`

    Whether the reaction was successfully removed

    - `true`

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
reaction = client.chats.messages.reactions.delete(
    message_id="messageID",
    chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com",
    reaction_key="x",
)
print(reaction.chat_id)
```