API Reference
Attachments Summary
Overview
Get aggregate attachment counts for a conversation — broken down by media category — for tab badges and empty states in the shared media panel of the chat UI.
Returns totals for all attachments plus per-type counts (image, video, audio, document, other) so you can show "Photos (25)" style labels without loading the full attachment list.
When to use this endpoint?
Use Attachments Summary when:
- Opening the shared media section from a conversation info sheet.
- Rendering category tabs (All, Photos, Videos, Documents) with count badges.
- Deciding whether to show an empty state before calling the paginated attachments list.
- Refreshing counts after a new file is sent in the thread.
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
The data object contains count fields:
| Field | Description |
|---|---|
| all | Total attachments across all categories in the conversation. |
| image | Count of image attachments (photos, screenshots, etc.). |
| video | Count of video attachments. |
| audio | Count of audio / voice attachments. |
| document | Count of document attachments (PDF, Office files, etc.). |
| other | Count of attachments that do not fit the above categories. |
{baseUrl}/api/{apiVersion}/conversation/attachments/summary?conversationId={conversationId}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). |
Success Response (HTTP 200 OK)
On success, data returns per-category counts. Use these values for tab badges before loading the paginated attachment list.
{
"success": true,
"message": "Attachment summary fetched successfully",
"data": {
"all": 42,
"image": 25,
"video": 6,
"audio": 3,
"document": 7,
"other": 1
},
"error": null
}Common Errors
Summary fails when the token is missing, the conversation does not exist, or the user is not allowed to view it.
HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 404 Not Found — Conversation missing
{
"success": false,
"message": "Conversation not found",
"data": null,
"error": null
}HTTP 403 Forbidden — Access denied
{
"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 the attachment summary. |
Best Practices
- Fetch summary when the media panel opens; defer the paginated list until the user selects a category tab.
- Hide tabs where the count is zero to keep the UI clean (e.g. skip Video when
video: 0). - Refresh summary after sending a new attachment so badge counts stay in sync with the thread.
- Pair with Conversation Attachments — summary for counts, list endpoint for actual files.
- Always send tenant headers with the chat user Bearer token over HTTPS.
Media tabs ready
Render category tabs and badges from this summary. When the user picks a tab, load files with Conversation Attachments using the matching type filter.