## Create

`$ beeper-desktop-cli chats create`

**post** `/v1/chats`

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

### Parameters

- `--account-id: string`

  Account to create or start the chat on.

- `--allow-invite: optional boolean`

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

- `--message-text: optional string`

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

- `--mode: optional "create" or "start"`

  Operation mode. Defaults to 'create' when omitted.

- `--participant-id: optional array of string`

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

- `--title: optional string`

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

- `--type: optional "single" or "group"`

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

- `--user: optional object { id, email, fullName, 2 more }`

  Required when mode='start'. Merged user-like contact payload used to resolve the best identifier.

### Returns

- `ChatNewResponse: object { chatID, status }`

  - `chatID: string`

    Newly created chat ID.

  - `status: optional "existing" or "created"`

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

    - `"existing"`

    - `"created"`

### Example

```cli
beeper-desktop-cli chats create \
  --account-id accountID
```