## Create

`client.chats.create(ChatCreateParamsbody, RequestOptionsoptions?): ChatCreateResponse`

**post** `/v1/chats`

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

### Parameters

- `body: ChatCreateParams`

  - `accountID: string`

    Account to create or start the chat on.

  - `allowInvite?: boolean`

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

  - `messageText?: string`

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

  - `mode?: "create" | "start"`

    Operation mode. Defaults to 'create' when omitted.

    - `"create"`

    - `"start"`

  - `participantIDs?: Array<string>`

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

  - `title?: string`

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

  - `type?: "single" | "group"`

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

    - `"single"`

    - `"group"`

  - `user?: User`

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

    - `id?: string`

      Known user ID when available.

    - `email?: string`

      Email candidate.

    - `fullName?: string`

      Display name hint used for ranking only.

    - `phoneNumber?: string`

      Phone number candidate (E.164 preferred).

    - `username?: string`

      Username/handle candidate.

### Returns

- `ChatCreateResponse`

  - `chatID: string`

    Newly created chat ID.

  - `status?: "existing" | "created"`

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

    - `"existing"`

    - `"created"`

### Example

```typescript
import BeeperDesktop from '@beeper/desktop-api';

const client = new BeeperDesktop();

const chat = await client.chats.create({ accountID: 'accountID' });

console.log(chat.chatID);
```