Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

Create or start a chat

client.chats.create(ChatCreateParams { params } params?, RequestOptionsoptions?): 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
params: ChatCreateParams { params }
params?: UnionMember0 { accountID, mode, user, 2 more } | UnionMember1 { accountID, participantIDs, type, 3 more }
One of the following:
UnionMember0 { accountID, mode, user, 2 more }
accountID: string

Account to create or start the chat on.

mode: "start"

Operation mode. Use ‘start’ to resolve a user/contact and start a direct chat.

user: User { id, email, fullName, 2 more }

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.

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.

UnionMember1 { accountID, participantIDs, type, 3 more }
accountID: string

Account to create or start the chat on.

participantIDs: Array<string>

User IDs to include in the new chat.

type: "single" | "group"

‘single’ requires exactly one participantID; ‘group’ supports multiple participants and optional title.

One of the following:
"single"
"group"
messageText?: string

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

mode?: "create"

Operation mode. Defaults to ‘create’ when omitted.

title?: string

Optional title for group chats; ignored for single chats on most platforms.

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.

One of the following:
"existing"
"created"

Create or start a chat

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

const client = new BeeperDesktop({
  accessToken: process.env['BEEPER_ACCESS_TOKEN'], // This is the default and can be omitted
});

const chat = await client.chats.create();

console.log(chat.chatID);
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}
Returns Examples
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}