## Create

**post** `/v1/chats`

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

### Body Parameters

- `accountID: string`

  Account to create or start the chat on.

- `allowInvite: optional boolean`

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

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

  - `"create"`

  - `"start"`

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

  - `"single"`

  - `"group"`

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

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

  - `id: optional string`

    Known user ID when available.

  - `email: optional string`

    Email candidate.

  - `fullName: optional string`

    Display name hint used for ranking only.

  - `phoneNumber: optional string`

    Phone number candidate (E.164 preferred).

  - `username: optional string`

    Username/handle candidate.

### Returns

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

```http
curl http://localhost:23373/v1/chats \
    -H 'Content-Type: application/json' \
    -d '{
          "accountID": "accountID"
        }'
```