API Reference
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. |
{baseUrl}/api/{apiVersion}/message/mentioned-messages?page=1&limit=20Authentication
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).
{
"success": true,
"message": "Mentioned messages fetched successfully",
"data": {
"list": [
{
"_id": "6a4f...b21c",
"conversationId": {
"_id": "69b12d08db7dd594ba013ebc",
"groupName": "Dev Team",
"conversationType": "group"
},
"content": "Hey @Alice can you review this?",
"type": "text",
"sender": {
"_id": "69a91733afd8cb7180a63fb2",
"name": "Bob",
"image": null
},
"mentions": ["69a5546ff54a9af3316020c9"],
"createdAt": "2026-07-20T09:04:09.578Z"
}
],
"page": 1,
"limit": 20,
"hasMore": false
},
"error": null
}Common Errors
HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}| 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
hasMorerather 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
conversationIdand 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.