Social API reference

Social API · Conversations

post/v1/communities/{community_id}/conversations/{conversation_id}/messagesAuth

Send a message in the conversation. Pass an `Idempotency-Key` header to make retries safe — a retried send never delivers the message twice.

Path parameters

community_id*string

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

conversation_id*string

Conversation UUID.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. Replays return the original response with `Idempotent-Replay: true`; same key + different body returns 409 `IDEMPOTENCY_KEY_REUSE`.

Request body

actor_id*string · uuid

The sender — social actor UUID. Standardized name (task 008 / G11); the persisted `sender_id` is set from it.

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

bodystring

Message body. Required when `kind="text"`. 1..10000 chars after trim.

Example: "Hey!"

kindenum (5)

Message type. Default `text`.

Example: "text"

attachmentsarray

Legacy URL attachments. Prefer `assets`.

assetsarray

Ordered image attachments (task 019). Each references a `ready` asset in this community owned by the sender. Max 20.

reply_to_idstring · uuid

Threaded inline reply target.

Response · 201 Message sent.

id*string · uuid

Message UUID.

Example: "eeeeeeee-0000-0000-0000-000000000001"

conversation_id*string · uuid

Conversation UUID.

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

community_id*string · uuid

Owning community UUID.

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

sender_id*string · uuid

Sender actor UUID.

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

kind*object

Message type. `system` messages are written by the service (member added, role changed).

Example: "text"

body*string

Message body. Returns `"(deleted)"` when soft-deleted.

Example: "Hey there."

attachments*array

Legacy URL attachments. New messages attach assets (`assets`).

assets*array

Ordered image attachments (task 019). Ref-only; resolve renditions via GET /assets/:id.

reply_to_id*string · uuid

Threaded inline reply target.

Example: null

edited_at*string · date-time

ISO timestamp of the last edit; `null` for never-edited.

Example: null

deleted_at*string · date-time

ISO timestamp when soft-deleted; `null` until then.

Example: null

reaction_counts*object

Map of reaction type to count, denormalised on the message row in lock-step with the DM-reaction writes.

Example: {"like":1}

created_at*string · date-time

ISO timestamp.

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

Example

Request

POST https://social.productcraft.co/v1/communities/{community_id}/conversations/{conversation_id}/messages
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "body": "Hey!",
  "kind": "text",
  "attachments": [
    {
      "kind": "image",
      "url": "https://cdn.example/attachments/abc.png"
    }
  ],
  "assets": [
    {
      "asset_id": "eeeeeeee-0000-0000-0000-000000000001",
      "alt_text": "string"
    }
  ],
  "reply_to_id": "00000000-0000-0000-0000-000000000000"
}

Response

{
  "id": "eeeeeeee-0000-0000-0000-000000000001",
  "conversation_id": "11111111-2222-3333-4444-555555555555",
  "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "sender_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "kind": "text",
  "body": "Hey there.",
  "attachments": [
    {
      "kind": "image",
      "url": "https://cdn.example/attachments/abc.png"
    }
  ],
  "assets": [
    {
      "asset_id": "eeeeeeee-0000-0000-0000-000000000001",
      "alt_text": "A golden retriever on a beach"
    }
  ],
  "reply_to_id": null,
  "edited_at": null,
  "deleted_at": null,
  "reaction_counts": {
    "like": 1
  },
  "created_at": "2026-05-01T12:00:00.000Z"
}