Update chat

PATCH/v1/chats/{chatID}

Update supported chat fields. Non-empty draft objects are accepted only when the current draft is empty. Send draft=null to clear the draft before setting new draft text or attachments.

Path ParametersExpand Collapse

chatID: string

Chat ID. Input routes also accept the local chat ID from this Beeper Desktop installation when available.

Body ParametersJSONExpand Collapse

description: optional string

Group chat description/topic. Support depends on the chat account and chat permissions.

draft: optional object { text, attachments }

Draft object to set or clear. Non-empty drafts are only accepted when the current draft is empty. Send draft=null to clear text and attachments together before setting a new draft.

text: string

Draft text. Plain text and Markdown are converted to Matrix HTML with the same rules used by send and edit.

attachments: optional map[object { uploadID, id, duration, 4 more } ]

Draft attachments keyed by attachment ID. Each attachment must reference an uploadID returned by the upload file endpoint.

uploadID: string

Upload ID from uploadAsset endpoint. Required to reference uploaded files.

id: optional string

Optional draft attachment identifier. If omitted, a new identifier is generated.

duration: optional number

Duration in seconds (optional override of cached value)

fileName: optional string

Filename (optional override of cached value)

mimeType: optional string

MIME type (optional override of cached value)

size: optional object { height, width }

Dimensions (optional override of cached value)

height: number

width: number

type: optional "image" or "video" or "audio" or 4 more

Attachment type hint (image, video, audio, file, gif, voice-note, sticker). If omitted, auto-detected from mimeType

One of the following:

"image"

"video"

"audio"

"file"

"gif"

"voice-note"

"sticker"

imgURL: optional string

Local filesystem path to a group chat avatar image. Support depends on the chat account and chat permissions.

isArchived: optional boolean

Archive or unarchive the chat.

isLowPriority: optional boolean

Mark or unmark the chat as low priority when supported by the account.

isMuted: optional boolean

Mute or unmute the chat.

isPinned: optional boolean

Pin or unpin the chat when supported by the account.

messageExpirySeconds: optional number

Disappearing-message timer in seconds, or null to clear when supported.

minimum0

title: optional string

Custom chat title. Support depends on the chat account and chat permissions.

ReturnsExpand Collapse

Chat object { id, accountID, network, 21 more }

id: string

Unique identifier of the chat across Beeper.

accountID: string

Account ID this chat belongs to.

network: string

Display-only human-readable account/network name.

participants: object { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: array of User { id, cannotMessage, email, 5 more }

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

isAdmin: optional boolean

True if this participant has admin privileges in the chat.

isNetworkBot: optional boolean

True if this participant represents a network or bridge bot.

isPending: optional boolean

True if this participant has been invited but has not joined yet.

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.

One of the following:

"single"

"group"

unreadCount: number

Number of unread messages.

capabilities: optional object { allowedReactions, archive, attachments, 24 more }

Chat capabilities reported by the platform.

allowedReactions: optional array of string

Allowed Unicode reactions. Omitted means all emoji reactions are allowed.

archive: optional boolean

True if archive/unarchive is supported.

attachments: optional map[object { mimeTypes, caption, maxCaptionLength, 5 more } ]

Supported attachment message types and their per-type constraints, keyed by Matrix msgtype or pseudo-msgtype (for example m.image, m.video, org.matrix.msc3245.voice). Missing message types should be treated as rejected.

mimeTypes: map[-2 or -1 or 0 or 2 more]

Supported MIME types or MIME patterns for this file message type. Missing MIME types should be treated as rejected.

One of the following:

-2

-1

caption: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

maxCaptionLength: optional number

Maximum caption length when captions are supported.

maxDuration: optional number

Maximum audio or video duration in seconds.

maxHeight: optional number

Maximum image or video height in pixels.

maxSize: optional number

Maximum file size in bytes.

maxWidth: optional number

Maximum image or video width in pixels.

viewOnce: optional boolean

True if this file type can be sent as view-once media.

customEmojiReactions: optional boolean

True if custom emoji reactions are supported.

delete: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

deleteChat: optional boolean

True if deleting chats for the authenticated user is supported.

deleteChatForEveryone: optional boolean

True if deleting chats for everyone is supported.

deleteForMe: optional boolean

True if deleting messages only for the authenticated user is supported.

deleteMaxAge: optional number

Maximum message age for delete-for-everyone, in seconds.

disappearingTimer: optional object { omitEmptyTimer, timers, types }

Disappearing-message timer capabilities.

omitEmptyTimer: optional boolean

True if empty timer objects should be omitted from message content.

timers: optional array of number

Allowed disappearing timer values in milliseconds. Omitted means any timer is allowed.

types: optional array of "afterRead" or "afterSend"

Supported disappearing timer types.

One of the following:

"afterRead"

"afterSend"

edit: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

editMaxAge: optional number

Maximum message age for edits, in seconds.

editMaxCount: optional number

Maximum number of edits allowed for one message.

formatting: optional map[-2 or -1 or 0 or 2 more]

Supported rich-text formatting features keyed by feature name (for example bold, inline_code, code_block.syntax_highlighting). Omitted means no formatting support is advertised.

One of the following:

-2

-1

locationMessage: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

markAsUnread: optional boolean

True if marking chats unread is supported.

maxTextLength: optional number

Maximum length of normal text messages.

messageRequest: optional object { acceptWithButton, acceptWithMessage }

Message request capabilities.

acceptWithButton: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

acceptWithMessage: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

participantActions: optional object { ban, invite, kick, 2 more }

Participant management capabilities.

ban: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

invite: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

kick: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

leave: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

revokeInvite: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

poll: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

reaction: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

reactionCount: optional number

Maximum number of reactions allowed on a single message.

readReceipts: optional boolean

True if read receipts are supported.

reply: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

state: optional object { avatar, description, disappearingTimer, title }

Chat state update capabilities.

avatar: optional object { level }

Chat avatar state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

description: optional object { level }

Chat description/topic state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

disappearingTimer: optional object { level }

Disappearing-message timer state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

title: optional object { level }

Chat title state capability.

level: -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

thread: optional -2 or -1 or 0 or 2 more

-2: rejected, -1: dropped, 0: unsupported, 1: partially supported, 2: fully supported.

One of the following:

-2

-1

typingNotifications: optional boolean

True if typing notifications are supported.

description: optional string

Group chat description/topic when available.

draft: optional object { text, attachments }

Current draft object for this chat, or null when no draft is set.

text: string

Matrix HTML draft body.

attachments: optional map[object { id, type, audioDurationSeconds, 6 more } ]

Draft attachments keyed by attachment ID.

id: string

Draft attachment identifier.

type: "file" or "gif" or "recorded_audio"

Draft attachment type. GIF and recorded audio are mutually exclusive types.

One of the following:

"file"

"gif"

"recorded_audio"

audioDurationSeconds: optional number

Audio duration in seconds if known.

fileName: optional string

Original filename if available.

filePath: optional string

Local filesystem path for the draft attachment.

fileSize: optional number

File size in bytes if known.

mimeType: optional string

MIME type if known.

size: optional object { height, width }

Pixel dimensions of the attachment.

height: optional number

width: optional number

stickerID: optional string

Sticker identifier if the draft attachment is a sticker.

imgURL: optional string

Local filesystem path to the chat avatar image when available.

isArchived: optional boolean

True if chat is archived.

isLowPriority: optional boolean

True if chat is marked low priority.

isMarkedUnread: optional boolean

True if the chat was explicitly marked unread by the authenticated user.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

isReadOnly: optional boolean

True if messages cannot be sent in this chat.

lastActivity: optional string

Timestamp of last activity.

formatdate-time

lastReadMessageSortKey: optional string

Last read message sortKey.

localChatID: optional string

Local chat ID specific to this Beeper Desktop installation.

messageExpirySeconds: optional number

Disappearing-message timer in seconds when available.

reminder: optional object { dismissOnIncomingMessage, remindAt }

Current reminder for this chat, or null when no reminder is set.

dismissOnIncomingMessage: optional boolean

Cancel reminder if someone messages in the chat.

remindAt: optional string

Timestamp when the reminder should trigger.

formatdate-time

snooze: optional object { snoozeUntil, userSnoozedAt }

Current snooze state for this chat, or null when no snooze is set.

snoozeUntil: optional string

Timestamp when the snooze expires.

formatdate-time

userSnoozedAt: optional string

Timestamp when the user set the snooze.

formatdate-time

unreadMentionsCount: optional number

Number of unread messages that mention the authenticated user or @room.

Update chat

curl http://localhost:23373/v1/chats/$CHAT_ID \
    -X PATCH \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN"

{
  "id": "!whatsapp_15550101002:ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc.local-whatsapp.localhost",
  "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
  "network": "WhatsApp",
  "participants": {
    "hasMore": false,
    "items": [
      {
        "id": "@15550101002:local-whatsapp.localhost",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Kishan Bagaria",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "+15550101002",
        "username": "username",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc:local-whatsapp.localhost",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Batuhan İçöz",
        "imgURL": "imgURL",
        "isSelf": true,
        "phoneNumber": "phoneNumber",
        "username": "username",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      }
    ],
    "total": 2
  },
  "title": "Kishan Bagaria",
  "type": "single",
  "unreadCount": 0,
  "capabilities": {
    "allowedReactions": [
      "string"
    ],
    "archive": true,
    "attachments": {
      "foo": {
        "mimeTypes": {
          "foo": -2
        },
        "caption": -2,
        "maxCaptionLength": 0,
        "maxDuration": 0,
        "maxHeight": 0,
        "maxSize": 0,
        "maxWidth": 0,
        "viewOnce": true
      }
    },
    "customEmojiReactions": true,
    "delete": -2,
    "deleteChat": true,
    "deleteChatForEveryone": true,
    "deleteForMe": true,
    "deleteMaxAge": 0,
    "disappearingTimer": {
      "omitEmptyTimer": true,
      "timers": [
        0
      ],
      "types": [
        "afterRead"
      ]
    },
    "edit": -2,
    "editMaxAge": 0,
    "editMaxCount": 0,
    "formatting": {
      "foo": -2
    },
    "locationMessage": -2,
    "markAsUnread": true,
    "maxTextLength": 0,
    "messageRequest": {
      "acceptWithButton": -2,
      "acceptWithMessage": -2
    },
    "participantActions": {
      "ban": -2,
      "invite": -2,
      "kick": -2,
      "leave": -2,
      "revokeInvite": -2
    },
    "poll": -2,
    "reaction": -2,
    "reactionCount": 0,
    "readReceipts": true,
    "reply": -2,
    "state": {
      "avatar": {
        "level": -2
      },
      "description": {
        "level": -2
      },
      "disappearingTimer": {
        "level": -2
      },
      "title": {
        "level": -2
      }
    },
    "thread": -2,
    "typingNotifications": true
  },
  "description": "description",
  "draft": {
    "text": "text",
    "attachments": {
      "foo": {
        "id": "id",
        "type": "file",
        "audioDurationSeconds": 0,
        "fileName": "fileName",
        "filePath": "filePath",
        "fileSize": 0,
        "mimeType": "mimeType",
        "size": {
          "height": 0,
          "width": 0
        },
        "stickerID": "stickerID"
      }
    }
  },
  "imgURL": "imgURL",
  "isArchived": false,
  "isLowPriority": true,
  "isMarkedUnread": true,
  "isMuted": false,
  "isPinned": false,
  "isReadOnly": true,
  "lastActivity": "2026-05-05T20:11:54.000Z",
  "lastReadMessageSortKey": "455171049984",
  "localChatID": "5639",
  "messageExpirySeconds": 0,
  "reminder": {
    "dismissOnIncomingMessage": true,
    "remindAt": "2025-08-31T23:30:12.520Z"
  },
  "snooze": {
    "snoozeUntil": "2025-08-31T23:30:12.520Z",
    "userSnoozedAt": "2025-08-31T23:30:12.520Z"
  },
  "unreadMentionsCount": 0
}

Returns Examples

{
  "id": "!whatsapp_15550101002:ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc.local-whatsapp.localhost",
  "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
  "network": "WhatsApp",
  "participants": {
    "hasMore": false,
    "items": [
      {
        "id": "@15550101002:local-whatsapp.localhost",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Kishan Bagaria",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "+15550101002",
        "username": "username",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc:local-whatsapp.localhost",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Batuhan İçöz",
        "imgURL": "imgURL",
        "isSelf": true,
        "phoneNumber": "phoneNumber",
        "username": "username",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      }
    ],
    "total": 2
  },
  "title": "Kishan Bagaria",
  "type": "single",
  "unreadCount": 0,
  "capabilities": {
    "allowedReactions": [
      "string"
    ],
    "archive": true,
    "attachments": {
      "foo": {
        "mimeTypes": {
          "foo": -2
        },
        "caption": -2,
        "maxCaptionLength": 0,
        "maxDuration": 0,
        "maxHeight": 0,
        "maxSize": 0,
        "maxWidth": 0,
        "viewOnce": true
      }
    },
    "customEmojiReactions": true,
    "delete": -2,
    "deleteChat": true,
    "deleteChatForEveryone": true,
    "deleteForMe": true,
    "deleteMaxAge": 0,
    "disappearingTimer": {
      "omitEmptyTimer": true,
      "timers": [
        0
      ],
      "types": [
        "afterRead"
      ]
    },
    "edit": -2,
    "editMaxAge": 0,
    "editMaxCount": 0,
    "formatting": {
      "foo": -2
    },
    "locationMessage": -2,
    "markAsUnread": true,
    "maxTextLength": 0,
    "messageRequest": {
      "acceptWithButton": -2,
      "acceptWithMessage": -2
    },
    "participantActions": {
      "ban": -2,
      "invite": -2,
      "kick": -2,
      "leave": -2,
      "revokeInvite": -2
    },
    "poll": -2,
    "reaction": -2,
    "reactionCount": 0,
    "readReceipts": true,
    "reply": -2,
    "state": {
      "avatar": {
        "level": -2
      },
      "description": {
        "level": -2
      },
      "disappearingTimer": {
        "level": -2
      },
      "title": {
        "level": -2
      }
    },
    "thread": -2,
    "typingNotifications": true
  },
  "description": "description",
  "draft": {
    "text": "text",
    "attachments": {
      "foo": {
        "id": "id",
        "type": "file",
        "audioDurationSeconds": 0,
        "fileName": "fileName",
        "filePath": "filePath",
        "fileSize": 0,
        "mimeType": "mimeType",
        "size": {
          "height": 0,
          "width": 0
        },
        "stickerID": "stickerID"
      }
    }
  },
  "imgURL": "imgURL",
  "isArchived": false,
  "isLowPriority": true,
  "isMarkedUnread": true,
  "isMuted": false,
  "isPinned": false,
  "isReadOnly": true,
  "lastActivity": "2026-05-05T20:11:54.000Z",
  "lastReadMessageSortKey": "455171049984",
  "localChatID": "5639",
  "messageExpirySeconds": 0,
  "reminder": {
    "dismissOnIncomingMessage": true,
    "remindAt": "2025-08-31T23:30:12.520Z"
  },
  "snooze": {
    "snoozeUntil": "2025-08-31T23:30:12.520Z",
    "userSnoozedAt": "2025-08-31T23:30:12.520Z"
  },
  "unreadMentionsCount": 0
}

Update chat

Path ParametersExpand Collapse

Body ParametersJSONExpand Collapse

ReturnsExpand Collapse

Update chat

Returns Examples

What can I help you with?