Create a conversation
create a new conversation as the token tenant — a 1:1 creator DM (participantId) or a group conversation (groupName + participantIds). Creates a real channel (external side effect), so sandbox/test grants are rejected. Requires the messages:write scope.
Authorizations
OAuth 2.1 authorization code + PKCE (S256). Tokens are tenant-bound (company_id) and scoped. Discover endpoints via /.well-known/oauth-authorization-server.
Body
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.
1:1 mode: the other participant (creator) id. Mutually exclusive with groupName.
Group mode: the group conversation name. Creates a real group channel. Mutually exclusive with participantId.
Group mode: additional member Firebase user ids (may be empty). Each id must resolve to an existing user (404 'Creator not found' otherwise).
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.
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).