Skip to content
Beeper Developer Docs
Download Beeper
Changelog

Desktop API Changelog

v4.2.808 (2026-05-06) Latest

Part of Beeper Desktop 4.2.808.

Added

  • New chat actions - You can now update more chat state directly through the API.

    API changes:

  • Start direct chats - Starting a direct chat now has a dedicated endpoint.

    API changes:

    • Added POST /v1/chats/start.
    • Direct-message start behavior moved out of POST /v1/chats.
    • POST /v1/chats/start accepts accountID, user, optional messageText, and optional allowInvite.

  • Message management - Individual messages can now be fetched and deleted.

    API changes:

  • Richer chat metadata - Chat responses now include more state and display information.

    API changes:

    • Added fields to the Chat response, including network, description, imgURL, draft, reminder, snooze, isReadOnly, isMarkedUnread, isLowPriority, messageExpirySeconds, unreadMentionsCount, and capabilities.
    • network is now always included in chat responses from GET /v1/chats/{chatID}, GET /v1/chats, and GET /v1/chats/search.

  • Richer message metadata - Message responses now include more delivery, edit, deletion, mention, link, and read-status information.

    API changes:

    • Added fields to the Message response, including type, editedTimestamp, sendStatus, isHidden, isDeleted, mentions, links, and seen.
    • Added attachment transcription metadata.

  • Better message pagination - Message listing now returns explicit cursors for paging in both directions.

    API changes:

    • ListMessagesOutput now includes required oldestCursor and newestCursor.
    • Cursor values are opaque and should not be parsed.

  • Account bridge metadata - Account responses now include bridge information, making it easier to understand which bridge or network backs each account.

    API changes:

    • Added Account.bridge to GET /v1/accounts responses.
    • Added optional Account.network.
    • No request changes are required; clients do not send bridge.

Breaking changes

  • Reaction removal URL changed - The reaction key is now part of the path instead of a query parameter.

    API changes:

    • Old: DELETE /v1/chats/{chatID}/messages/{messageID}/reactions?reactionKey=...
    • New: DELETE /v1/chats/{chatID}/messages/{messageID}/reactions/{reactionKey}

  • Chat creation no longer starts DMs - POST /v1/chats is now for creating chats. Starting a direct chat moved to POST /v1/chats/start. See the Start direct chats section above for the new request shape.

    API changes:

    • Removed mode from CreateChatInput.
    • Removed user from CreateChatInput.
    • Removed allowInvite from CreateChatInput.
    • CreateChatInput now requires type and participantIDs.

  • Response shapes are richer - Some endpoints now return full resource objects instead of small ID/success envelopes.

    API changes:

    • CreateChatOutput is now based on Chat.
    • EditMessageOutput is now based on Message.
    • Clients should prefer id over legacy chatID or messageID compatibility fields.

v4.2.557 (2026-02-13)

Added

Changed

  • Chat creation behavior - POST /v1/chats now supports mode=start to create or resolve direct chats from merged contact data and returns status=existing|created in that mode.
  • Account schema - network is no longer returned from Account; use accountID plus user and contact/query behavior instead.

v4.2.509 (2026-01-27)

Added

  • Assets - New streaming endpoint: GET /v1/assets/serve
    • Accepts mxc://, localmxc://, and file:// URLs.
    • Supports range requests for large media playback/seek.

v4.2.499 (2026-01-23)

Added

  • Message editing - New endpoint: PUT /v1/chats/{chatID}/messages/{messageID}.
  • Asset uploads - New endpoints:
    • POST /v1/assets/upload (multipart/form-data)
    • POST /v1/assets/upload/base64 (JSON base64 body)
  • Send message attachments - POST /v1/chats/{chatID}/messages now supports attachment payloads via uploadID.

Changed

  • Message schema - Added type and linkedMessageID fields in message responses.

v4.1.294 (2025-10-16)

REST API

  • Breaking - gRPC-style /v0 endpoints are deprecated in favor of RESTful /v1 endpoints
  • New - List endpoints for chats (/v1/chats) and messages (/v1/chats/:chatID/messages)
  • Fixed - Searching for chats no longer returns cached responses
Endpoint changes

Reference for old routes are published here.

EndpointRequest/Response
GET /v0/get-chat →
GET /v1/chats/{chatID}		Request chatID is now a path parameter; default maxParticipantCount -1 (was 20).
Response Unchanged.
POST /v0/create-chat →
POST /v1/chats		Request Unchanged.
Response Returns { "chatID": string }; HTTP status replaces the success flag.
POST /v0/send-message →
POST /v1/chats/{chatID}/messages		Request chatID moved to path; body now only text plus optional replyToMessageID.
Response success flag removed.
POST /v0/archive-chat →
POST /v1/chats/{chatID}/archive		Request chatID moved to path; body still optional archived boolean.
Response Success now 204 No Content (empty body).
POST /v0/set-chat-reminder →
POST /v1/chats/{chatID}/reminders		Request chatID moved to path; body still wraps reminder.
Response Success now 204 No Content (empty body).
POST /v0/clear-chat-reminder →
DELETE /v1/chats/{chatID}/reminders		Request Method is DELETE; chatID path param; no body.
Response Success now 204 No Content.
GET /v0/search-messages →
GET /v1/messages/search		Request Max limit now 20.
Response Unchanged; each page capped at 20 results.
GET /v0/search-users →
GET /v1/accounts/{accountID}/contacts		Request accountID moved into the path; query unchanged.
Response Unchanged.
GET /v0/get-accounts →
GET /v1/accounts		Request/Response Unchanged.
POST /v0/download-asset →
POST /v1/assets/download		Request/Response Unchanged.
POST /v0/open-app →
POST /v1/focus		Request/Response Unchanged.
GET /v0/search →
GET /v1/search		Request/Response Unchanged.
GET /v0/search-chats →
GET /v1/chats/search		Request/Response Unchanged.

MCP Server

We have an all new MCP server, and it’s open source!

  • Breaking - MCP server no longer supports Server-Side Events (SSE). If your preferred client does not support Streamable HTTP or stdio, get in touch for workarounds.

Everything should work as before. If you encounter any issues, please email us at help@beeper.com!

TypeScript SDK

  • Breaking - Some methods were reorganized
  • Breaking - client.token.* removed
  • New - client.chats.list() and client.messages.list(chatID)
Method changes
Old UsageNew UsageNotes
client.app.downloadAsset({ url })client.assets.download({ url })Resource renamed
client.app.open({ chatID, ... })client.focus({ chatID, ... })Moved to top-level
client.app.search({ query })client.search({ query })Moved to top-level
client.chats.retrieve({ chatID })client.chats.retrieve(chatID)chatID now path parameter
client.chats.archive({ chatID, archived })client.chats.archive(chatID, { archived })chatID now path parameter
client.chats.reminders.create({ chatID, reminder })client.chats.reminders.create(chatID, { reminder })chatID now path parameter
client.chats.reminders.delete({ chatID })client.chats.reminders.delete(chatID)chatID now path parameter
client.contacts.search({ accountID, query })client.accounts.contacts.search(accountID, { query })Moved to subresource; accountID now path parameter
client.messages.send({ chatID, text, ... })client.messages.send(chatID, { text, ... })chatID now path parameter
client.token.*N/ARemoved

v4.1.244 (2025-09-30)

Fixed

  • API responses no longer truncate the message text to 500 characters, increased the limit in the MCP responses to 1000

v4.1.239 (2025-09-26)

Added

  • Remote Access is now available, allowing advanced users to expose Beeper Desktop API to the internet. Read more here.
  • Authenticated responses from the Desktop API now returns the Desktop app version the user is on in the response headers (X-Beeper-Desktop-Version). You can use the token info endpoint as a no-op request to check the version.

v4.1.210 (2025-09-17)

Added

  • POST /v0/create-chat: create single or group chats using participant IDs, optional title, and initial message text (CreateChatOutput).
  • POST /v0/download-asset: fetch Matrix mxc:// assets and return a local srcURL (DownloadAssetOutput). Assets (avatars, message attachments) return a local file path if they are already downloaded. This method can be used to download assets that are not yet downloaded.
  • GET /v0/search: unified search returning top chats, participant matches, and first page of messages (UnifiedSearchOutput).
  • GET /v0/search-users: look up contacts on a specific account before creating chats (SearchUsersOutput).

Changed

  • POST /v0/open-app (OpenAppInput): new draftAttachmentPath; message jump now uses messageID.
  • GET /v0/search-chats (SearchChatsInput): consolidated literal query, new scope toggle (titles vs participants), removed participantQuery, dropped channel from type, boolean filters now nullable.
  • GET /v0/search-messages (SearchMessagesInput/SearchMessagesOutput): replaced onlyWith* flags with mediaTypes array (any/video/image/link/file); default page size documented as 20 with enforced cap; updated cursor examples; mute/low-priority filters nullable.
  • POST /v0/send-message (SendMessageOutput): response returns chatID and pendingMessageID instead of a final messageID.

Removed

  • POST /v0/download-attachment and GetAttachmentOutput superseded by the new download asset flow.

v4.1.169 (2025-09-02)

Starting from this version, Beeper Desktop API & MCP is now available to everyone on the stable version of the app.

Fixed

  • MCP: search_chats and get_chat now returns more information about a chat with explicit chatID and instructions for the LLM on how to use it

v4.1.155 (2025-08-31)

Added