Mentioned Messages

Overview

Retrieve every message across the signed-in user's conversations where they were @mentioned- the data behind a "Mentions" inbox. Unlike Pinned or Starred (which are scoped to one conversation), this spans all conversations the user belongs to.

Results are newest-first and paginated. Each item includes the sender and a light conversation reference, so you can render an inbox row and jump into the thread.

When to use this endpoint?

Use Mentioned Messages when:

Opening a "Mentions" inbox from the app header.
Showing a badge/list of messages that @mention the signed-in user across all their groups and DMs.
Letting the user jump from a mention to the message in context.

Membership-guarded: only conversations the user participates in are searched, so a user never sees mentions from a conversation they aren't in. Mentions are resolved server-side from the message text on send.

Response Data

Each item in data.list includes:

Field	Description
_id	Message id - use to scroll to the message in the thread.
conversationId	Populated conversation reference (`groupName`, `conversationType`) - label the inbox row and route to the right thread.
content	Message text (contains the inline `@Name` mention). Render with your mention highlighter.
sender	Who wrote it - `name` and `image`.
mentions	Array of mentioned user ids (includes the signed-in user).
createdAt	ISO timestamp - used for the newest-first sort.

GET{baseUrl}/api/{apiVersion}/message/mentioned-messages?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 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
page	Optional	1	1-based page number. Default 1.
limit	Optional	20	Page size. Default 20, max 50.

Success Response (HTTP 200 OK)

Returns a list of mentioned-message summaries plus paging info (page, limit, hasMore).

json

1{2  "success": true,3  "message": "Mentioned messages fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6a4f...b21c",8        "conversationId": {9          "_id": "69b12d08db7dd594ba013ebc",10          "groupName": "Dev Team",11          "conversationType": "group"12        },13        "content": "Hey @Alice can you review this?",14        "type": "text",15        "sender": {16          "_id": "69a91733afd8cb7180a63fb2",17          "name": "Bob",18          "image": null19        },20        "mentions": ["69a5546ff54a9af3316020c9"],21        "createdAt": "2026-07-20T09:04:09.578Z"22      }23    ],24    "page": 1,25    "limit": 20,26    "hasMore": false27  },28  "error": null29}

Common Errors

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching mentions.

Best Practices

Load when the user opens the mentions inbox; paginate with hasMore rather than fetching everything at once.
Render the inline @Namewith your mention highlighter so the user's own mention stands out.
On row tap, route to conversationId and scroll to _id.
Pair with the mention push notification so a new mention both notifies the user and appears here.

Mentions inbox ready

Bind the list to your mentions inbox. A ticket/row selects a conversation and jumps to the mentioned message in the thread.

Overview

Results are newest-first and paginated. Each item includes the sender and a light conversation reference, so you can render an inbox row and jump into the thread.

When to use this endpoint?

Use Mentioned Messages when:

Opening a "Mentions" inbox from the app header.
Showing a badge/list of messages that @mention the signed-in user across all their groups and DMs.
Letting the user jump from a mention to the message in context.

Response Data

Each item in data.list includes:

Field	Description
_id	Message id - use to scroll to the message in the thread.
conversationId	Populated conversation reference (`groupName`, `conversationType`) - label the inbox row and route to the right thread.
content	Message text (contains the inline `@Name` mention). Render with your mention highlighter.
sender	Who wrote it - `name` and `image`.
mentions	Array of mentioned user ids (includes the signed-in user).
createdAt	ISO timestamp - used for the newest-first sort.

Header

Value

Description

Authorization

Bearer <access_token>

Chat user Access Token (Bearer) for the signed-in 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

page

Optional

1-based page number. Default 1.

limit

Optional

Page size. Default 20, max 50.

Success Response (HTTP 200 OK)

Returns a list of mentioned-message summaries plus paging info (page, limit, hasMore).

json

1{2  "success": true,3  "message": "Mentioned messages fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6a4f...b21c",8        "conversationId": {9          "_id": "69b12d08db7dd594ba013ebc",10          "groupName": "Dev Team",11          "conversationType": "group"12        },13        "content": "Hey @Alice can you review this?",14        "type": "text",15        "sender": {16          "_id": "69a91733afd8cb7180a63fb2",17          "name": "Bob",18          "image": null19        },20        "mentions": ["69a5546ff54a9af3316020c9"],21        "createdAt": "2026-07-20T09:04:09.578Z"22      }23    ],24    "page": 1,25    "limit": 20,26    "hasMore": false27  },28  "error": null29}

Common Errors

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching mentions.

Best Practices

Load when the user opens the mentions inbox; paginate with hasMore rather than fetching everything at once.
Render the inline @Namewith your mention highlighter so the user's own mention stands out.
On row tap, route to conversationId and scroll to _id.
Pair with the mention push notification so a new mention both notifies the user and appears here.