## Create

`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').

### Parameters

- `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.

  - `"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.

  - `"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.

### Returns

- `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.

    - `"existing"`

    - `"created"`

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
chat = client.chats.create(
    account_id="accountID",
)
print(chat.chat_id)
```