API Reference

Pinned Messages

Overview

Retrieve pinned messages for a conversation — for the pinned banner at the top of the chat thread and the full pinned-messages list in the messaging UI.

Each row wraps the underlying message (text or media preview) with who pinned it and when, so you can show a compact banner or a scrollable pinned panel without loading the entire message history.

When to use this endpoint?

Use Pinned Messages when:

Rendering the pinned-message banner above the chat input when a conversation has active pins.
Opening a "Pinned messages" sheet or modal from the thread header menu.
Refreshing pin state after a user pins or unpins a message via socket or action API.
Showing who pinned each message and when for group transparency.

Part of the Chat Messages APIs for the chat package/SDK (not Platform → Messages). Requires a chat user Access Token for the signed-in messaging participant.

Response Data

Each item in data.list typically includes:

Field	Description
_id	Pin record id — distinct from the message `messageId._id`.
messageId	Nested message summary for display: `_id`, `content` (text), `type`, `status`, and for media types `attachmentUrl`. Tap to scroll to the message in the thread.
pinnedBy	User who pinned the message — `_id` and `name` for attribution in the banner or list.
pinnedAt	ISO timestamp when the message was pinned — use for sort order and "pinned on" labels.

GET

{baseUrl}/api/{apiVersion}/message/pinned-messages?conversationId={conversationId}&page=1&limit=15&sort=createdAt&sortType=desc

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Chat user Access Token (Bearer) for the signed-in messaging participant.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Query Parameters

Parameter	Required	Example	Description
conversationId	Required	{{conversationId}}	Conversation _id to scope results to (24-char Mongo ObjectId).
page	Optional	1	Page number, 1-based. Default 1.
limit	Optional	15	Page size — items per page. Default 10.
sort	Optional	createdAt	Field name to sort by. Default "createdAt".
sortType	Optional	desc	Sort direction: "asc" or "desc". Default "desc".

Success Response (HTTP 200 OK)

On success, the API returns a list of pin records. Use messageId for preview text or thumbnails in the pinned banner; use pinnedBy and pinnedAt for attribution.

json

{
  "success": true,
  "message": "Pinned messages fetched successfully",
  "data": {
    "list": [
      {
        "messageId": {
          "_id": "69786e9583a5ab2f5e986a87",
          "content": "hello",
          "type": "text",
          "status": "read"
        },
        "pinnedBy": {
          "_id": "694bac9cd60aff7378ddc77a",
          "name": "test 3 user"
        },
        "pinnedAt": "2026-01-27T10:41:24.618Z",
        "_id": "697896549266218f5eec5014"
      },
      {
        "messageId": {
          "_id": "6979b8c271b296d1ac960536",
          "type": "image",
          "attachmentUrl": "https://fastly.picsum.photos/id/237/200/300.jpg?hmac=TmmQSbShHz9CdQm0NkEjx1Dyh_Y984R9LpNrpvH2D_U",
          "status": "read"
        },
        "pinnedBy": {
          "_id": "694bac9cd60aff7378ddc77a",
          "name": "test 3 user"
        },
        "pinnedAt": "2026-01-28T07:44:33.308Z",
        "_id": "6979be6171b296d1ac96057b"
      }
    ]
  },
  "error": null
}

Common Errors

Pinned list fails when the token is missing, the user is not a participant, or the conversation does not exist in this tenant.

HTTP 401 Unauthorized — No token

json

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

HTTP 403 Forbidden — Access denied

json

{
  "success": false,
  "message": "Access denied: insufficient permissions",
  "data": null,
  "error": null
}

HTTP 404 Not Found — Conversation not found

json

{
  "success": false,
  "message": "Conversation not found",
  "data": null,
  "error": null
}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	User is not a participant or lacks access to this conversation.
404 Not Found	`conversationId` does not exist or is not visible in this tenant.
500 Internal Server Error	An unexpected error occurred while fetching pinned messages.

Best Practices

Fetch on thread open alongside List Messages when pinnedCount from the conversation list is greater than zero.
Show the most recent pin in a compact banner; link to the full list when multiple pins exist.
On pin/unpin socket events, patch local state or refetch this endpoint instead of reloading the entire message history.
Use messageId._id to scroll to the original message in the thread when the user taps a pinned row.
Always send tenant headers with the chat user Bearer token over HTTPS.

Pins ready

Bind the list to your pinned banner and pinned-messages panel. Pair with List Messages so tapping a pin scrolls to the message in the active thread.

Field

Description

_id

Pin record id — distinct from the message messageId._id.

messageId

Nested message summary for display: _id, content (text), type, status, and for media types attachmentUrl. Tap to scroll to the message in the thread.

pinnedBy

User who pinned the message — _id and name for attribution in the banner or list.

pinnedAt

ISO timestamp when the message was pinned — use for sort order and "pinned on" labels.

Header

Value

Description

Authorization

Bearer <access_token>

Chat user Access Token (Bearer) for the signed-in messaging participant.

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

Parameter

Required

Example

Description

conversationId

Required

Conversation _id to scope results to (24-char Mongo ObjectId).

page

Optional

Page number, 1-based. Default 1.

limit

Optional

Page size — items per page. Default 10.

sort

Optional

createdAt

Field name to sort by. Default "createdAt".

sortType

Optional

desc

Sort direction: "asc" or "desc". Default "desc".

{ "success": true, "message": "Pinned messages fetched successfully", "data": { "list": [ { "messageId": { "_id": "69786e9583a5ab2f5e986a87", "content": "hello", "type": "text", "status": "read" }, "pinnedBy": { "_id": "694bac9cd60aff7378ddc77a", "name": "test 3 user" }, "pinnedAt": "2026-01-27T10:41:24.618Z", "_id": "697896549266218f5eec5014" }, { "messageId": { "_id": "6979b8c271b296d1ac960536", "type": "image", "attachmentUrl": "https://fastly.picsum.photos/id/237/200/300.jpg?hmac=TmmQSbShHz9CdQm0NkEjx1Dyh_Y984R9LpNrpvH2D_U", "status": "read" }, "pinnedBy": { "_id": "694bac9cd60aff7378ddc77a", "name": "test 3 user" }, "pinnedAt": "2026-01-28T07:44:33.308Z", "_id": "6979be6171b296d1ac96057b" } ] }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

User is not a participant or lacks access to this conversation.

404 Not Found

conversationId does not exist or is not visible in this tenant.

500 Internal Server Error

An unexpected error occurred while fetching pinned messages.