Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

Start a direct chat

chats.start(ChatStartParams**kwargs) -> ChatStartResponse
POST/v1/chats/start

Resolve a user/contact and open a direct chat. Reuses and returns an existing direct chat when one is found. Available in Beeper Desktop v4.2.808+.

ParametersExpand Collapse
account_id: str

Account to create or start the chat on.

user: User

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.

allow_invite: Optional[bool]

Whether invite-based DM creation is allowed when required by the platform.

message_text: Optional[str]

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

ReturnsExpand Collapse
class ChatStartResponse: …
Deprecatedchat_id: str

DEPRECATED - use id instead. Compatibility alias for older clients.

Deprecatedstatus: Optional[Literal["existing", "created"]]

DEPRECATED - legacy start-chat status for older clients. New clients should inspect the returned Chat instead.

One of the following:
"existing"
"created"

Start a direct chat

import os
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop(
    access_token=os.environ.get("BEEPER_ACCESS_TOKEN"),  # This is the default and can be omitted
)
response = client.chats.start(
    account_id="accountID",
    user={},
)
print(response)
{
  "id": "!team_launch_planning:beeper.com",
  "accountID": "matrix",
  "network": "Beeper",
  "participants": {
    "hasMore": false,
    "items": [
      {
        "id": "@kishanbagaria:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Kishan Bagaria",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "kishanbagaria:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@batuhan:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Batuhan İçöz",
        "imgURL": "imgURL",
        "isSelf": true,
        "phoneNumber": "phoneNumber",
        "username": "batuhan:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@mattwondra:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Matt Wondra",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "mattwondra:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@adamvy:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Adam Van Ymeren",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "adamvy:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      }
    ],
    "total": 4
  },
  "title": "Launch Planning",
  "type": "group",
  "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:12:30.969Z",
  "lastReadMessageSortKey": "862756563",
  "localChatID": "5541",
  "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,
  "chatID": "!team_launch_planning:beeper.com",
  "status": "created"
}
Returns Examples
{
  "id": "!team_launch_planning:beeper.com",
  "accountID": "matrix",
  "network": "Beeper",
  "participants": {
    "hasMore": false,
    "items": [
      {
        "id": "@kishanbagaria:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Kishan Bagaria",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "kishanbagaria:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@batuhan:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Batuhan İçöz",
        "imgURL": "imgURL",
        "isSelf": true,
        "phoneNumber": "phoneNumber",
        "username": "batuhan:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@mattwondra:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Matt Wondra",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "mattwondra:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@adamvy:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Adam Van Ymeren",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "adamvy:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      }
    ],
    "total": 4
  },
  "title": "Launch Planning",
  "type": "group",
  "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:12:30.969Z",
  "lastReadMessageSortKey": "862756563",
  "localChatID": "5541",
  "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,
  "chatID": "!team_launch_planning:beeper.com",
  "status": "created"
}