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
params: Optional[Params]
One of the following:
class ParamsUnionMember0: …
account_id: str

Account to create or start the chat on.

mode: Literal["start"]

Operation mode. Use ‘start’ to resolve a user/contact and start a direct chat.

user: ParamsUnionMember0User

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. Used for mode=‘start’.

message_text: Optional[str]

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

class ParamsUnionMember1: …
account_id: str

Account to create or start the chat on.

participant_ids: Sequence[str]

User IDs to include in the new chat.

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

‘single’ requires exactly one participantID; ‘group’ supports multiple participants and optional title.

One of the following:
"single"
"group"
message_text: Optional[str]

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

mode: Optional[Literal["create"]]

Operation mode. Defaults to ‘create’ when omitted.

title: Optional[str]

Optional title for group chats; ignored for single chats on most platforms.

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.

One of the following:
"existing"
"created"

Create or start a 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
)
chat = client.chats.create()
print(chat.chat_id)
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}
Returns Examples
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}