API Reference

Conversation Attachments

Overview

List paginated file and media attachments shared in a conversation — for the shared media gallery, document browser, and attachment search inside the chat UI.

Filter by type, sender, date range, or free-text search. Each item includes download URL, dimensions, size, and sender info for grid or list rendering.

When to use this endpoint?

Use Conversation Attachments when:

Opening the shared media panel from a group or DM info sheet.
Showing image thumbnails, PDFs, or other files sent in the thread.
Filtering the gallery to images only via type=image, or narrowing by sender and date range.
Paginating through a long attachment history as the user scrolls.

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

Response Data

Each item in data.list typically includes:

Field	Description
_id	Attachment record id.
messageId	Source message id — use to jump to the message in the thread.
conversationId	Parent conversation id (matches query `conversationId`).
sender	Uploader with `_id`, `name`, and optional `profileImage`.
url / filename / fileType	Download URL, original filename, and MIME type for preview or download.
size	File size in bytes.
width / height / duration	Image/video dimensions and media duration where applicable; null for documents.
uploadedAt / createdAt	ISO timestamps for when the file was uploaded.

GET{baseUrl}/api/{apiVersion}/conversation/attachments?conversationId={conversationId}&type=image&page=1&limit=20

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).
type	Optional	image	Filter by type (message type: text / image / file).
search	Optional	—	Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint's searchable fields.
senderId	Optional	—	Filter by sender userId (24-char Mongo ObjectId).
startDate	Optional	—	Range start date, ISO 8601 (e.g. "2026-06-01"). UTC.
endDate	Optional	—	Range end date, ISO 8601 (e.g. "2026-06-30"). UTC.
page	Optional	1	Page number, 1-based. Default 1.
limit	Optional	20	Page size — items per page. Default 10.

Success Response (HTTP 200 OK)

On success, the API returns a paginated list of attachments. The example includes one image and one PDF from the same conversation.

json

{
  "success": true,
  "message": "Attachments fetched successfully",
  "data": {
    "list": [
      {
        "_id": "665f...0001",
        "messageId": "665f...0001",
        "conversationId": "699fe...645c",
        "sender": {
          "_id": "665f...34cd",
          "name": "Smith William",
          "profileImage": null
        },
        "url": "https://example.com/profile-image.png",
        "filename": "profile-photo.png",
        "fileType": "image/png",
        "size": 20480,
        "width": 800,
        "height": 600,
        "duration": null,
        "uploadedAt": "2026-06-19T08:58:00.000Z",
        "createdAt": "2026-06-19T08:58:00.000Z"
      },
      {
        "_id": "665f...0001",
        "messageId": "665f...0001",
        "conversationId": "699fe...645c",
        "sender": {
          "_id": "665f...34cd",
          "name": "Smith William",
          "profileImage": null
        },
        "url": "https://example.com/report.pdf",
        "filename": "report.pdf",
        "fileType": "application/pdf",
        "size": 20480,
        "width": null,
        "height": null,
        "duration": null,
        "uploadedAt": "2026-06-19T08:58:00.000Z",
        "createdAt": "2026-06-19T08:58:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 2,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "pageSize": 20
    }
  },
  "error": null
}

Common Errors

Attachments fail when the token is missing, the conversation does not exist, or the user is not allowed to view it.

HTTP 401 Unauthorized — No token

json

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

HTTP 404 Not Found — Conversation missing

json

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

HTTP 403 Forbidden — Access denied

json

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

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	No conversation exists for the given `conversationId`.
403 Forbidden	Signed-in user is not a participant or lacks permission to view attachments in this conversation.
500 Internal Server Error	An unexpected error occurred while fetching attachments.

Best Practices

Call Attachments Summary first for tab counts, then load this endpoint when the user opens a specific category.
Use type filters in the gallery UI instead of filtering large lists client-side.
Lazy-load thumbnails; open full-size previews or downloads via url on user action.
Link each attachment to its messageId so users can jump to the original message in the thread.
Always send tenant headers with the chat user Bearer token over HTTPS.

Media gallery ready

Render the attachment grid or list from this response. Pair with Attachments Summary for category tabs and counts in the shared media panel.

Field

Description

_id

Attachment record id.

messageId

Source message id — use to jump to the message in the thread.

conversationId

Parent conversation id (matches query conversationId).

sender

Uploader with _id, name, and optional profileImage.

url / filename / fileType

Download URL, original filename, and MIME type for preview or download.

size

File size in bytes.

width / height / duration

Image/video dimensions and media duration where applicable; null for documents.

uploadedAt / createdAt

ISO timestamps for when the file was uploaded.

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).

type

Optional

image

Filter by type (message type: text / image / file).

Optional

—

Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint's searchable fields.

senderId

Optional

—

Filter by sender userId (24-char Mongo ObjectId).

startDate

Optional

—

Range start date, ISO 8601 (e.g. "2026-06-01"). UTC.

endDate

Optional

—

Range end date, ISO 8601 (e.g. "2026-06-30"). UTC.

page

Optional

Page number, 1-based. Default 1.

limit

Optional

Page size — items per page. Default 10.

{ "success": true, "message": "Attachments fetched successfully", "data": { "list": [ { "_id": "665f...0001", "messageId": "665f...0001", "conversationId": "699fe...645c", "sender": { "_id": "665f...34cd", "name": "Smith William", "profileImage": null }, "url": "https://example.com/profile-image.png", "filename": "profile-photo.png", "fileType": "image/png", "size": 20480, "width": 800, "height": 600, "duration": null, "uploadedAt": "2026-06-19T08:58:00.000Z", "createdAt": "2026-06-19T08:58:00.000Z" }, { "_id": "665f...0001", "messageId": "665f...0001", "conversationId": "699fe...645c", "sender": { "_id": "665f...34cd", "name": "Smith William", "profileImage": null }, "url": "https://example.com/report.pdf", "filename": "report.pdf", "fileType": "application/pdf", "size": 20480, "width": null, "height": null, "duration": null, "uploadedAt": "2026-06-19T08:58:00.000Z", "createdAt": "2026-06-19T08:58:00.000Z" } ], "pagination": { "currentPage": 1, "totalCount": 2, "hasNextPage": false, "hasPreviousPage": false, "pageSize": 20 } }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

404 Not Found

No conversation exists for the given conversationId.

403 Forbidden

Signed-in user is not a participant or lacks permission to view attachments in this conversation.

500 Internal Server Error

An unexpected error occurred while fetching attachments.