Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

Create or start a chat

chats.create(ChatCreateParams**kwargs) -> ChatCreateResponse
POST/v1/chats

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

ParametersExpand Collapse
account_id: str

Account to create or start the chat on.

allow_invite: Optional[bool]

Whether invite-based DM creation is allowed when required by the platform. Used for mode='start'.

message_text: Optional[str]

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

mode: Optional[Literal["create", "start"]]

Operation mode. Defaults to 'create' when omitted.

Accepts one of the following:
"create"
"start"
participant_ids: Optional[SequenceNotStr[str]]

Required when mode='create'. User IDs to include in the new chat.

title: Optional[str]

Optional title for group chats when mode='create'; ignored for single chats on most platforms.

type: Optional[Literal["single", "group"]]

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

Accepts one of the following:
"single"
"group"
user: Optional[User]

Required when mode='start'. 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.

ReturnsExpand Collapse
class ChatCreateResponse: …
chat_id: str

Newly created chat ID.

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

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

Accepts one of the following:
"existing"
"created"

Create or start a chat

from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
chat = client.chats.create(
    account_id="accountID",
)
print(chat.chat_id)
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}
Returns Examples
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}