/v1/communities/{community_id}/conversationsAuthOpen a conversation. Default `kind="direct"` is the naturally-idempotent 1-on-1 path (get-or-create by participant pair). Pass `kind="group"` with `actor_ids` for a multi-participant chat — group creates always insert a new row, so pass an `Idempotency-Key` header to make group-create retries safe.
Path parameters
community_id*stringSocial community UUID. Must belong to the PAK's workspace.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. Mostly useful for `kind="group"` (direct conversations are get-or-create by participant pair anyway). Replays return the original response with `Idempotent-Replay: true`; same key + different body returns 409 `IDEMPOTENCY_KEY_REUSE`.
Request body
actor_id*string · uuidSocial actor UUID opening the conversation.
Example: "aaaaaaaa-0000-0000-0000-000000000001"
kindenum (2)Conversation shape. Default `direct`.
Example: "direct"
recipient_actor_idstring · uuidFor 1-on-1 (`kind="direct"`): the other participant — social actor UUID. Required when kind=direct.
Example: "aaaaaaaa-0000-0000-0000-000000000002"
actor_idsarrayFor groups (`kind="group"`): initial members (excluding the creator). Required when kind=group. Capped by `community.settings.max_group_conversation_size` (default 50).
Example: ["aaaaaaaa-0000-0000-0000-000000000002","aaaaaaaa-0000-0000-0000-000000000003"]
namestringOptional group display name. Ignored for 1-on-1.
Response · 201 Conversation created or (1-on-1 only) returned.
id*string · uuidConversation UUID.
Example: "11111111-2222-3333-4444-555555555555"
community_id*string · uuidOwning community UUID.
Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"
kind*objectConversation shape — 1-on-1 (`direct`) or multi-participant (`group`).
Example: "direct"
name*stringGroup display name; null for 1-on-1.
Example: null
created_by*stringSocial actor UUID of the group founder; null for legacy / 1-on-1.
Example: null
participants*arrayParticipants, joined-at ascending.
unread_count*numberUnread messages for the requesting actor (task 024) — messages from others created after the requester's last_read_at. Embedded on list + single GET for inbox badges.
Example: 0
created_at*string · date-timeISO timestamp.
Example: "2026-05-01T12:00:00.000Z"
updated_at*string · date-timeISO timestamp.
Example: "2026-05-01T12:00:00.000Z"
last_message_at*string · date-timeISO timestamp of the most recent message (or conversation create when no messages yet).
Example: "2026-05-01T12:00:00.000Z"
Example
Request
POST https://social.productcraft.co/v1/communities/{community_id}/conversations
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
"kind": "direct",
"recipient_actor_id": "aaaaaaaa-0000-0000-0000-000000000002",
"actor_ids": [
"aaaaaaaa-0000-0000-0000-000000000002",
"aaaaaaaa-0000-0000-0000-000000000003"
],
"name": "string"
}Response
{
"id": "11111111-2222-3333-4444-555555555555",
"community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
"kind": "direct",
"name": null,
"created_by": null,
"participants": [
{
"actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
"joined_at": "2026-05-01T12:00:00.000Z",
"last_read_at": null,
"muted": false,
"muted_until": null,
"pinned": false,
"role": "member"
}
],
"unread_count": 0,
"created_at": "2026-05-01T12:00:00.000Z",
"updated_at": "2026-05-01T12:00:00.000Z",
"last_message_at": "2026-05-01T12:00:00.000Z"
}