API Reference
Search Message Context
Overview
Load the thread window around a search hit — for jumping from search results into the conversation with the matched message highlighted and in view.
Returns highlightMessageId plus a list of full message objects (same shape as List Messages) spanning messages before and after the hit.
When to use this endpoint?
Use Search Message Context when:
- The user taps a result from Search Messages and you need to open the thread at that message.
- Rendering surrounding messages so the hit has conversational context above and below.
- Scrolling to and visually highlighting the matched message in the message list.
- Prefetching a slice of the thread before merging with live socket updates.
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.
Workflow:Search Messages → user picks a hit → Search Message Context with that message's _id → open the thread scrolled to highlightMessageId.
Response Data
The data object includes:
| Field | Description |
|---|---|
| highlightMessageId | The message id to scroll to and highlight in the thread — same as the search hit messageId you passed in the query. Use this to apply a highlight style and call scrollIntoView (or your virtual list equivalent). |
| list | Array of full message objects around the hit — same shape as List Messages (sender, content, reactions, read receipts, pinned/starred flags, and timestamps). Render these directly in your message list component. |
{baseUrl}/api/{apiVersion}/message/searched-message/context?messageId={messageId}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 | Example | Required | Description |
|---|---|---|---|
| messageId | {{messageId}} | Required | Search hit message _id (24-char Mongo ObjectId) from Search Messages results. |
Success Response (HTTP 200 OK)
On success, data.highlightMessageId identifies the message to highlight and data.list contains the surrounding thread slice.
{
"success": true,
"message": "Messages fetched successfully",
"data": {
"highlightMessageId": "6a4e...ef5c",
"list": [
{
"_id": "6a4e...ef5c",
"conversationId": "6a4e...ef5c",
"sender": {
"_id": "6a4e...ef5c",
"name": "John Doe"
},
"isSystemMessage": false,
"content": "Hi",
"type": "text",
"isEdited": false,
"isForwarded": false,
"status": "read",
"readBy": [
{
"_id": "6a4e...ef5c",
"name": "Jane Doe"
}
],
"starredBy": [],
"deletedFor": [],
"isDeletedForEveryone": false,
"reactions": [],
"createdAt": "2026-03-11T05:07:49.051Z",
"updatedAt": "2026-03-11T05:28:34.875Z",
"__v": 0,
"isLoggedUserStarred": false,
"isPinnedMessage": false
}
]
},
"error": null
}Common Errors
Context fetch fails when the token is missing, the message 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 — Message missing
{
"success": false,
"message": "Message not found",
"data": null,
"error": "Message not found"
}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 message exists for the given messageId, or its conversation is missing in this tenant. |
| 403 Forbidden | Signed-in user is not a participant or lacks permission to view this message's conversation. |
| 500 Internal Server Error | An unexpected error occurred while fetching message context. |
Best Practices
- Call this endpoint only after the user selects a search result — not on every keystroke during search.
- Match the row whose
_idequalshighlightMessageIdand apply a temporary highlight animation. - Merge
data.listinto your thread state by message id to avoid duplicates when live messages arrive. - Reuse the same message bubble component as List Messages since the object shape is identical.
- Always send tenant headers with the chat user Bearer token over HTTPS.
Search-to-thread flow ready
Chain Search Messages → Search Message Context → open conversation scrolled to highlightMessageId. Use List Messages for normal pagination above and below this window.