Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

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’).

Body ParametersJSONExpand Collapse
params: optional object { accountID, mode, user, 2 more } or object { accountID, participantIDs, type, 3 more }
One of the following:
object { 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: object { id, email, fullName, 2 more }

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.

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.

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

Account to create or start the chat on.

participantIDs: array of string

User IDs to include in the new chat.

type: "single" or "group"

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

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

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

mode: optional "create"

Operation mode. Defaults to ‘create’ when omitted.

title: optional string

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

ReturnsExpand Collapse
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.

One of the following:
"existing"
"created"

Create or start a chat

curl http://localhost:23373/v1/chats \
    -X POST \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN"
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}
Returns Examples
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}