Create or start a chat

client.chats.create(, ?): ChatCreateResponse { chatID, status }

POST/v1/chats

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

ParametersExpand Collapse

body: ChatCreateParams { accountID, allowInvite, messageText, 5 more }

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.

Accepts one of the following:

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

Accepts one of the following:

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

ReturnsExpand Collapse

ChatCreateResponse { chatID, status }

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.

Accepts one of the following:

"existing"

"created"

Create or start a chat

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

const client = new BeeperDesktop();

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

console.log(chat.chatID);

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

Returns Examples

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