Social API reference

Social API · Conversations

post/v1/communities/{community_id}/conversationsAuth

Open 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*string

Social community UUID. Must belong to the PAK's workspace.

Headers

Idempotency-Keystring

Opaque 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 · uuid

Social actor UUID opening the conversation.

Example: "aaaaaaaa-0000-0000-0000-000000000001"

kindenum (2)

Conversation shape. Default `direct`.

Example: "direct"

recipient_actor_idstring · uuid

For 1-on-1 (`kind="direct"`): the other participant — social actor UUID. Required when kind=direct.

Example: "aaaaaaaa-0000-0000-0000-000000000002"

actor_idsarray

For 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"]

namestring

Optional group display name. Ignored for 1-on-1.

Response · 201 Conversation created or (1-on-1 only) returned.

id*string · uuid

Conversation UUID.

Example: "11111111-2222-3333-4444-555555555555"

community_id*string · uuid

Owning community UUID.

Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"

kind*object

Conversation shape — 1-on-1 (`direct`) or multi-participant (`group`).

Example: "direct"

name*string

Group display name; null for 1-on-1.

Example: null

created_by*string

Social actor UUID of the group founder; null for legacy / 1-on-1.

Example: null

participants*array

Participants, joined-at ascending.

unread_count*number

Unread 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-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

updated_at*string · date-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

last_message_at*string · date-time

ISO 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"
}