# Chats

## Retrieve

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

Retrieve chat details including metadata, participants, and latest message

### Path Parameters

- `chatID: string`

  Unique identifier of the chat.

### Query Parameters

- `maxParticipantCount: optional number`

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

### Returns

- `Chat = object { id, accountID, participants, 9 more }`

  - `id: string`

    Unique identifier of the chat across Beeper.

  - `accountID: string`

    Account ID this chat belongs to.

  - `participants: object { hasMore, items, total }`

    Chat participants information.

    - `hasMore: boolean`

      True if there are more participants than included in items.

    - `items: array of User`

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

      - `id: string`

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

      - `cannotMessage: optional boolean`

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

        Email address if known. Not guaranteed verified.

      - `fullName: optional string`

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

      - `imgURL: optional string`

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

      - `isSelf: optional boolean`

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

      - `phoneNumber: optional string`

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

      - `username: optional string`

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

    - `total: number`

      Total number of participants in the chat.

  - `title: string`

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

  - `type: "single" or "group"`

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

    - `"single"`

    - `"group"`

  - `unreadCount: number`

    Number of unread messages.

  - `isArchived: optional boolean`

    True if chat is archived.

  - `isMuted: optional boolean`

    True if chat notifications are muted.

  - `isPinned: optional boolean`

    True if chat is pinned.

  - `lastActivity: optional string`

    Timestamp of last activity.

  - `lastReadMessageSortKey: optional string`

    Last read message sortKey.

  - `localChatID: optional string`

    Local chat ID specific to this Beeper Desktop installation.

### Example

```http
curl http://localhost:23373/v1/chats/$CHAT_ID
```

## Create

**post** `/v1/chats`

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

### Body Parameters

- `accountID: string`

  Account to create or start the chat on.

- `allowInvite: optional boolean`

  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 "create" or "start"`

  Operation mode. Defaults to 'create' when omitted.

  - `"create"`

  - `"start"`

- `participantIDs: optional array of 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 "single" or "group"`

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

  - `"single"`

  - `"group"`

- `user: optional object { id, email, fullName, 2 more }`

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

  - `id: optional string`

    Known user ID when available.

  - `email: optional string`

    Email candidate.

  - `fullName: optional string`

    Display name hint used for ranking only.

  - `phoneNumber: optional string`

    Phone number candidate (E.164 preferred).

  - `username: optional string`

    Username/handle candidate.

### Returns

- `chatID: string`

  Newly created chat ID.

- `status: optional "existing" or "created"`

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

  - `"existing"`

  - `"created"`

### Example

```http
curl http://localhost:23373/v1/chats \
    -H 'Content-Type: application/json' \
    -d '{
          "accountID": "accountID"
        }'
```

## List

**get** `/v1/chats`

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

### Query Parameters

- `accountIDs: optional array of 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 "after" or "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

- `hasMore: boolean`

  True if additional results can be fetched using the provided cursors.

- `items: array of Chat`

  Chats ordered by last activity timestamp (most recent first).

  - `preview: optional Message`

    Last message preview for this chat, if available.

    - `id: string`

      Message ID.

    - `accountID: string`

      Beeper account ID the message belongs to.

    - `chatID: string`

      Unique identifier of the chat.

    - `senderID: string`

      Sender user ID.

    - `sortKey: string`

      A unique, sortable key used to sort messages.

    - `timestamp: string`

      Message timestamp.

    - `attachments: optional array of Attachment`

      Attachments included with this message, if any.

      - `type: "unknown" or "img" or "video" or "audio"`

        Attachment type.

        - `"unknown"`

        - `"img"`

        - `"video"`

        - `"audio"`

      - `id: optional string`

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

      - `duration: optional number`

        Duration in seconds (audio/video).

      - `fileName: optional string`

        Original filename if available.

      - `fileSize: optional number`

        File size in bytes if known.

      - `isGif: optional boolean`

        True if the attachment is a GIF.

      - `isSticker: optional boolean`

        True if the attachment is a sticker.

      - `isVoiceNote: optional boolean`

        True if the attachment is a voice note.

      - `mimeType: optional string`

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

      - `posterImg: optional string`

        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 object { height, width }`

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

        - `height: optional number`

        - `width: optional number`

      - `srcURL: optional string`

        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.

    - `isSender: optional boolean`

      True if the authenticated user sent the message.

    - `isUnread: optional boolean`

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

    - `linkedMessageID: optional string`

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

    - `reactions: optional array of Reaction`

      Reactions to the message, if any.

      - `id: string`

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

      - `participantID: string`

        User ID of the participant who reacted.

      - `reactionKey: string`

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

      - `emoji: optional boolean`

        True if the reactionKey is an emoji.

      - `imgURL: optional string`

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

    - `senderName: optional string`

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

    - `text: optional string`

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

    - `type: optional "TEXT" or "NOTICE" or "IMAGE" or 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"`

- `newestCursor: string`

  Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect.

- `oldestCursor: string`

  Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect.

### Example

```http
curl http://localhost:23373/v1/chats
```

## Search

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

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

### Query Parameters

- `accountIDs: optional array of 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 "after" or "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 "primary" or "low-priority" or "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"`

- `includeMuted: optional boolean`

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

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

- `lastActivityBefore: optional string`

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

- `limit: optional number`

  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 "titles" or "participants"`

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

  - `"titles"`

  - `"participants"`

- `type: optional "single" or "group" or "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"`

- `unreadOnly: optional boolean`

  Set to true to only retrieve chats that have unread messages

### Returns

- `hasMore: boolean`

  True if additional results can be fetched using the provided cursors.

- `items: array of Chat`

  Chats matching the filters.

  - `id: string`

    Unique identifier of the chat across Beeper.

  - `accountID: string`

    Account ID this chat belongs to.

  - `participants: object { hasMore, items, total }`

    Chat participants information.

    - `hasMore: boolean`

      True if there are more participants than included in items.

    - `items: array of User`

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

      - `id: string`

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

      - `cannotMessage: optional boolean`

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

        Email address if known. Not guaranteed verified.

      - `fullName: optional string`

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

      - `imgURL: optional string`

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

      - `isSelf: optional boolean`

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

      - `phoneNumber: optional string`

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

      - `username: optional string`

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

    - `total: number`

      Total number of participants in the chat.

  - `title: string`

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

  - `type: "single" or "group"`

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

    - `"single"`

    - `"group"`

  - `unreadCount: number`

    Number of unread messages.

  - `isArchived: optional boolean`

    True if chat is archived.

  - `isMuted: optional boolean`

    True if chat notifications are muted.

  - `isPinned: optional boolean`

    True if chat is pinned.

  - `lastActivity: optional string`

    Timestamp of last activity.

  - `lastReadMessageSortKey: optional string`

    Last read message sortKey.

  - `localChatID: optional string`

    Local chat ID specific to this Beeper Desktop installation.

- `newestCursor: string`

  Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect.

- `oldestCursor: string`

  Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect.

### Example

```http
curl http://localhost:23373/v1/chats/search
```

## Archive

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

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

### Path Parameters

- `chatID: string`

  Unique identifier of the chat.

### Body Parameters

- `archived: optional boolean`

  True to archive, false to unarchive

### Example

```http
curl http://localhost:23373/v1/chats/$CHAT_ID/archive \
    -X POST
```

## Domain Types

### Chat

- `Chat = object { id, accountID, participants, 9 more }`

  - `id: string`

    Unique identifier of the chat across Beeper.

  - `accountID: string`

    Account ID this chat belongs to.

  - `participants: object { hasMore, items, total }`

    Chat participants information.

    - `hasMore: boolean`

      True if there are more participants than included in items.

    - `items: array of User`

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

      - `id: string`

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

      - `cannotMessage: optional boolean`

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

        Email address if known. Not guaranteed verified.

      - `fullName: optional string`

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

      - `imgURL: optional string`

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

      - `isSelf: optional boolean`

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

      - `phoneNumber: optional string`

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

      - `username: optional string`

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

    - `total: number`

      Total number of participants in the chat.

  - `title: string`

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

  - `type: "single" or "group"`

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

    - `"single"`

    - `"group"`

  - `unreadCount: number`

    Number of unread messages.

  - `isArchived: optional boolean`

    True if chat is archived.

  - `isMuted: optional boolean`

    True if chat notifications are muted.

  - `isPinned: optional boolean`

    True if chat is pinned.

  - `lastActivity: optional string`

    Timestamp of last activity.

  - `lastReadMessageSortKey: optional string`

    Last read message sortKey.

  - `localChatID: optional string`

    Local chat ID specific to this Beeper Desktop installation.

# Reminders

## Create

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

Set a reminder for a chat at a specific time

### Path Parameters

- `chatID: string`

  Unique identifier of the chat.

### Body Parameters

- `reminder: object { remindAtMs, dismissOnIncomingMessage }`

  Reminder configuration

  - `remindAtMs: number`

    Unix timestamp in milliseconds when reminder should trigger

  - `dismissOnIncomingMessage: optional boolean`

    Cancel reminder if someone messages in the chat

### Example

```http
curl http://localhost:23373/v1/chats/$CHAT_ID/reminders \
    -H 'Content-Type: application/json' \
    -d '{
          "reminder": {
            "remindAtMs": 0
          }
        }'
```

## Delete

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

Clear an existing reminder from a chat

### Path Parameters

- `chatID: string`

  Unique identifier of the chat.

### Example

```http
curl http://localhost:23373/v1/chats/$CHAT_ID/reminders \
    -X DELETE
```

# Messages

# Reactions

## Add

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

Add a reaction to an existing message.

### Path Parameters

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

### Body Parameters

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

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

  Message ID.

- `reactionKey: string`

  Reaction key that was added

- `success: true`

  Whether the reaction was successfully added

  - `true`

- `transactionID: string`

  Transaction ID used for the reaction event

### Example

```http
curl http://localhost:23373/v1/chats/$CHAT_ID/messages/$MESSAGE_ID/reactions \
    -H 'Content-Type: application/json' \
    -d '{
          "reactionKey": "x"
        }'
```

## Delete

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

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

### Path Parameters

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

### Query Parameters

- `reactionKey: string`

  Reaction key to remove

### Returns

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

  Message ID.

- `reactionKey: string`

  Reaction key that was removed

- `success: true`

  Whether the reaction was successfully removed

  - `true`

### Example

```http
curl http://localhost:23373/v1/chats/$CHAT_ID/messages/$MESSAGE_ID/reactions \
    -X DELETE
```