# Chats ## Retrieve `client.chats.retrieve(stringchatID, ChatRetrieveParamsquery?, RequestOptionsoptions?): Chat` **get** `/v1/chats/{chatID}` Retrieve chat details including metadata, participants, and latest message ### Parameters - `chatID: string` Unique identifier of the chat. - `query: ChatRetrieveParams` - `maxParticipantCount?: number | null` Maximum number of participants to return. Use -1 for all; otherwise 0–500. Defaults to all (-1). ### Returns - `Chat` - `id: string` Unique identifier of the chat across Beeper. - `accountID: string` Account ID this chat belongs to. - `participants: Participants` Chat participants information. - `hasMore: boolean` True if there are more participants than included in items. - `items: Array` 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?: 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?: string` Email address if known. Not guaranteed verified. - `fullName?: string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL?: string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf?: boolean` True if this user represents the authenticated account's own identity. - `phoneNumber?: string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username?: 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" | "group"` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unreadCount: number` Number of unread messages. - `isArchived?: boolean` True if chat is archived. - `isMuted?: boolean` True if chat notifications are muted. - `isPinned?: boolean` True if chat is pinned. - `lastActivity?: string` Timestamp of last activity. - `lastReadMessageSortKey?: string` Last read message sortKey. - `localChatID?: string | null` Local chat ID specific to this Beeper Desktop installation. ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); const chat = await client.chats.retrieve('!NCdzlIaMjZUmvmvyHU:beeper.com'); console.log(chat.id); ``` ## Create `client.chats.create(ChatCreateParamsbody, RequestOptionsoptions?): ChatCreateResponse` **post** `/v1/chats` Create a single/group chat (mode='create') or start a direct chat from merged user data (mode='start'). ### Parameters - `body: ChatCreateParams` - `accountID: string` Account to create or start the chat on. - `allowInvite?: boolean` Whether invite-based DM creation is allowed when required by the platform. Used for mode='start'. - `messageText?: string` Optional first message content if the platform requires it to create the chat. - `mode?: "create" | "start"` Operation mode. Defaults to 'create' when omitted. - `"create"` - `"start"` - `participantIDs?: Array` Required when mode='create'. User IDs to include in the new chat. - `title?: string` Optional title for group chats when mode='create'; ignored for single chats on most platforms. - `type?: "single" | "group"` Required when mode='create'. 'single' requires exactly one participantID; 'group' supports multiple participants and optional title. - `"single"` - `"group"` - `user?: User` Required when mode='start'. Merged user-like contact payload used to resolve the best identifier. - `id?: string` Known user ID when available. - `email?: string` Email candidate. - `fullName?: string` Display name hint used for ranking only. - `phoneNumber?: string` Phone number candidate (E.164 preferred). - `username?: string` Username/handle candidate. ### Returns - `ChatCreateResponse` - `chatID: string` Newly created chat ID. - `status?: "existing" | "created"` Only returned in start mode. 'existing' means an existing chat was reused; 'created' means a new chat was created. - `"existing"` - `"created"` ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); const chat = await client.chats.create({ accountID: 'accountID' }); console.log(chat.chatID); ``` ## List `client.chats.list(ChatListParamsquery?, RequestOptionsoptions?): CursorNoLimit` **get** `/v1/chats` List all chats sorted by last activity (most recent first). Combines all accounts into a single paginated list. ### Parameters - `query: ChatListParams` - `accountIDs?: Array` Limit to specific account IDs. If omitted, fetches from all accounts. - `cursor?: string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `direction?: "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 - `ChatListResponse extends Chat` - `preview?: 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?: Array` Attachments included with this message, if any. - `type: "unknown" | "img" | "video" | "audio"` Attachment type. - `"unknown"` - `"img"` - `"video"` - `"audio"` - `id?: string` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `duration?: number` Duration in seconds (audio/video). - `fileName?: string` Original filename if available. - `fileSize?: number` File size in bytes if known. - `isGif?: boolean` True if the attachment is a GIF. - `isSticker?: boolean` True if the attachment is a sticker. - `isVoiceNote?: boolean` True if the attachment is a voice note. - `mimeType?: string` MIME type if known (e.g., 'image/png'). - `posterImg?: 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?: Size` Pixel dimensions of the attachment: width/height in px. - `height?: number` - `width?: number` - `srcURL?: 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?: boolean` True if the authenticated user sent the message. - `isUnread?: boolean` True if the message is unread for the authenticated user. May be omitted. - `linkedMessageID?: string` ID of the message this is a reply to, if any. - `reactions?: Array` 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?: boolean` True if the reactionKey is an emoji. - `imgURL?: string` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `senderName?: string` Resolved sender display name (impersonator/full name/username/participant name). - `text?: string` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `type?: "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 ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); // Automatically fetches more pages as needed. for await (const chatListResponse of client.chats.list()) { console.log(chatListResponse); } ``` ## Search `client.chats.search(ChatSearchParamsquery?, RequestOptionsoptions?): CursorSearch` **get** `/v1/chats/search` Search chats by title/network or participants using Beeper Desktop's renderer algorithm. ### Parameters - `query: ChatSearchParams` - `accountIDs?: Array` Provide an array of account IDs to filter chats from specific messaging accounts only - `cursor?: string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `direction?: "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?: "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"` - `includeMuted?: boolean | null` 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?: string` Provide an ISO datetime string to only retrieve chats with last activity after this time - `lastActivityBefore?: string` Provide an ISO datetime string to only retrieve chats with last activity before this time - `limit?: number` Set the maximum number of chats to retrieve. Valid range: 1-200, default is 50 - `query?: string` Literal token search (non-semantic). Use single words users type (e.g., "dinner"). When multiple words provided, ALL must match. Case-insensitive. - `scope?: "titles" | "participants"` Search scope: 'titles' matches title + network; 'participants' matches participant names. - `"titles"` - `"participants"` - `type?: "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"` - `unreadOnly?: boolean | null` Set to true to only retrieve chats that have unread messages ### Returns - `Chat` - `id: string` Unique identifier of the chat across Beeper. - `accountID: string` Account ID this chat belongs to. - `participants: Participants` Chat participants information. - `hasMore: boolean` True if there are more participants than included in items. - `items: Array` 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?: 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?: string` Email address if known. Not guaranteed verified. - `fullName?: string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL?: string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf?: boolean` True if this user represents the authenticated account's own identity. - `phoneNumber?: string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username?: 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" | "group"` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unreadCount: number` Number of unread messages. - `isArchived?: boolean` True if chat is archived. - `isMuted?: boolean` True if chat notifications are muted. - `isPinned?: boolean` True if chat is pinned. - `lastActivity?: string` Timestamp of last activity. - `lastReadMessageSortKey?: string` Last read message sortKey. - `localChatID?: string | null` Local chat ID specific to this Beeper Desktop installation. ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); // Automatically fetches more pages as needed. for await (const chat of client.chats.search()) { console.log(chat.id); } ``` ## Archive `client.chats.archive(stringchatID, ChatArchiveParamsbody?, RequestOptionsoptions?): 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. - `body: ChatArchiveParams` - `archived?: boolean` True to archive, false to unarchive ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); await client.chats.archive('!NCdzlIaMjZUmvmvyHU:beeper.com'); ``` ## Domain Types ### Chat - `Chat` - `id: string` Unique identifier of the chat across Beeper. - `accountID: string` Account ID this chat belongs to. - `participants: Participants` Chat participants information. - `hasMore: boolean` True if there are more participants than included in items. - `items: Array` 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?: 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?: string` Email address if known. Not guaranteed verified. - `fullName?: string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL?: string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf?: boolean` True if this user represents the authenticated account's own identity. - `phoneNumber?: string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username?: 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" | "group"` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unreadCount: number` Number of unread messages. - `isArchived?: boolean` True if chat is archived. - `isMuted?: boolean` True if chat notifications are muted. - `isPinned?: boolean` True if chat is pinned. - `lastActivity?: string` Timestamp of last activity. - `lastReadMessageSortKey?: string` Last read message sortKey. - `localChatID?: string | null` Local chat ID specific to this Beeper Desktop installation. # Reminders ## Create `client.chats.reminders.create(stringchatID, ReminderCreateParamsbody, RequestOptionsoptions?): void` **post** `/v1/chats/{chatID}/reminders` Set a reminder for a chat at a specific time ### Parameters - `chatID: string` Unique identifier of the chat. - `body: ReminderCreateParams` - `reminder: Reminder` Reminder configuration - `remindAtMs: number` Unix timestamp in milliseconds when reminder should trigger - `dismissOnIncomingMessage?: boolean` Cancel reminder if someone messages in the chat ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); await client.chats.reminders.create('!NCdzlIaMjZUmvmvyHU:beeper.com', { reminder: { remindAtMs: 0 }, }); ``` ## Delete `client.chats.reminders.delete(stringchatID, RequestOptionsoptions?): void` **delete** `/v1/chats/{chatID}/reminders` Clear an existing reminder from a chat ### Parameters - `chatID: string` Unique identifier of the chat. ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); await client.chats.reminders.delete('!NCdzlIaMjZUmvmvyHU:beeper.com'); ``` # Messages # Reactions ## Add `client.chats.messages.reactions.add(stringmessageID, ReactionAddParamsparams, RequestOptionsoptions?): ReactionAddResponse` **post** `/v1/chats/{chatID}/messages/{messageID}/reactions` Add a reaction to an existing message. ### Parameters - `messageID: string` - `params: ReactionAddParams` - `chatID: string` Path param: Unique identifier of the chat. - `reactionKey: string` Body param: Reaction key to add (emoji, shortcode, or custom emoji key) - `transactionID?: string` Body param: Optional transaction ID for deduplication and local echo tracking ### Returns - `ReactionAddResponse` - `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 ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); const response = await client.chats.messages.reactions.add('messageID', { chatID: '!NCdzlIaMjZUmvmvyHU:beeper.com', reactionKey: 'x', }); console.log(response.chatID); ``` ## Delete `client.chats.messages.reactions.delete(stringmessageID, ReactionDeleteParamsparams, RequestOptionsoptions?): ReactionDeleteResponse` **delete** `/v1/chats/{chatID}/messages/{messageID}/reactions` Remove the authenticated user's reaction from an existing message. ### Parameters - `messageID: string` - `params: ReactionDeleteParams` - `chatID: string` Path param: Unique identifier of the chat. - `reactionKey: string` Query param: Reaction key to remove ### Returns - `ReactionDeleteResponse` - `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 ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); const reaction = await client.chats.messages.reactions.delete('messageID', { chatID: '!NCdzlIaMjZUmvmvyHU:beeper.com', reactionKey: 'x', }); console.log(reaction.chatID); ```