Skip to content
Livstick Developers
v3 Request access

Messages

A message belongs to one container. List them across the platform, read one in full, or merge new fields into its data and privateData.

v3 Base URL https://client-api.v5.livstick.com/api/v3

Operations

This is where a gallery container’s messages are read — one call for the whole platform, filterable down to a single container or code group.

Method GET /messages

Scope messages:read

Lists messages for the authenticated platform, paginated.

Filter by crid to get every message in one container — the way to read all of a gallery container’s messages — or by codeGroupId to scope the list to one code group.

Parameters

Name In Type Required Description
limit Query integer Optional Maximum number of items to return. Default 50, maximum 200.
skip Query integer Optional Number of items to skip (pagination offset). Default 0.
crid Query string Optional Filter messages by container crid.
codeGroupId Query string Optional Filter messages by code group objectId.
redeemCode Query string Optional Filter messages by canonical redeem code.
order Query string Optional Sort field, prefixed with - for descending. Default -createdAt.

Response

json 200 
{
  "items": [
    {
      "objectId": "msg789",
      "state": "released",
      "type": 0,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "crid": "ORDER-123",
      "urid": "abc123xyz9",
      "codeGroupId": "grp456",
      "videoUrl": "https://cdn.example/video.mp4",
      "thumbUrl": "https://cdn.example/thumb.jpg",
      "redeemCode": "RDM-4F2A",
      "data": { "senderName": "John" },
      "privateData": { "orderId": "12345" },
      "analysisData": { "sentiment": "positive" },
      "language": "fr"
    }
  ],
  "total": 142,
  "limit": 50,
  "skip": 0
}

Method GET /messages/{messageId}

Scope messages:read

Retrieves full details for one message.

Returns data, privateData and analysisData in full, alongside the timeline dates the list endpoint omits.

Parameters

Name In Type Required Description
messageId Path string Required Unique identifier of the message.

Response

json 200 
{
  "objectId": "msg789",
  "state": "released",
  "type": 0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T14:00:00.000Z",
  "crid": "ORDER-123",
  "urid": "abc123xyz9",
  "codeGroupId": "grp456",
  "videoUrl": "https://cdn.example/video.mp4",
  "thumbUrl": "https://cdn.example/thumb.jpg",
  "data": { "senderName": "John", "senderEmail": "john@example.com" },
  "privateData": { "orderId": "12345", "internalNote": "VIP" },
  "analysisData": { "sentiment": "positive", "score": 0.95 },
  "language": "fr",
  "scheduledAt": "2025-02-14T00:00:00.000Z",
  "activatedAt": "2025-01-15T10:31:00.000Z",
  "viewedAt": "2025-01-20T18:00:00.000Z"
}

Method PATCH /messages/{messageId}

Scope messages:write

Merges fields into a message’s data and privateData.

Keys you provide overwrite existing keys; keys you omit are preserved. If a privateDataSchema is defined on the code group or the platform, privateData is validated against it before the merge is applied.

Parameters

Name In Type Required Description
messageId Path string Required Unique identifier of the message.
data Body object Optional Merged into message.data.
privateData Body object Optional Merged into message.privateData, validated against the code group or platform schema when one is defined.

Response

json 200 
{
  "result": "ok"
}