Create or start a chat

POST/v1/chats

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

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.

Accepts one of the following:

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

Accepts one of the following:

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

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.

Accepts one of the following:

"existing"

"created"

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

{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}

{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}