Skip to main content
POST
Create a conversation

Authorizations

Authorization
string
header
required

OAuth 2.1 authorization code + PKCE (S256). Tokens are tenant-bound (company_id) and scoped. Discover endpoints via /.well-known/oauth-authorization-server.

Body

application/json

Create a conversation as the token tenant (companyId injected from the token). Choose EXACTLY ONE mode: 1:1 DM — pass participantId (the creator id) and leave group fields unset; or group — pass groupName (plus optional participantIds and isProgramGroupChat) and leave participantId unset. Passing neither, or both, returns 400.

participantId
string

1:1 mode: the other participant (creator) id. Mutually exclusive with groupName.

groupName
string

Group mode: the group conversation name. Creates a real group channel. Mutually exclusive with participantId.

participantIds
string[]

Group mode: additional member Firebase user ids (may be empty). Each id must resolve to an existing user (404 'Creator not found' otherwise).

isProgramGroupChat
boolean

Group mode: true if this group chat belongs to a campaign/program. Defaults to false when omitted.

Response

The created conversation id and channel id.

data
object
required

Result of creating a conversation: the new Firestore DMs doc id plus the DM channel id (null when no channel was created). From createConversation (lib/api/messages/messages-create-conversation.usecase.ts:86).