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.

GET{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.

json

1{2  "success": true,3  "message": "Messages fetched successfully",4  "data": {5    "highlightMessageId": "6a4e...ef5c",6    "list": [7      {8        "_id": "6a4e...ef5c",9        "conversationId": "6a4e...ef5c",10        "sender": {11          "_id": "6a4e...ef5c",12          "name": "John Doe"13        },14        "isSystemMessage": false,15        "content": "Hi",16        "type": "text",17        "isEdited": false,18        "isForwarded": false,19        "status": "read",20        "readBy": [21          {22            "_id": "6a4e...ef5c",23            "name": "Jane Doe"24          }25        ],26        "starredBy": [],27        "deletedFor": [],28        "isDeletedForEveryone": false,29        "reactions": [],30        "createdAt": "2026-03-11T05:07:49.051Z",31        "updatedAt": "2026-03-11T05:28:34.875Z",32        "__v": 0,33        "isLoggedUserStarred": false,34        "isPinnedMessage": false35      }36    ]37  },38  "error": null39}

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

json

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

HTTP 404 Not Found - Message missing

json

1{2  "success": false,3  "message": "Message not found",4  "data": null,5  "error": "Message not found"6}

HTTP 404 Not Found - Conversation missing

json

1{2  "success": false,3  "message": "Conversation not found",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Access denied

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

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 _id equals highlightMessageId and apply a temporary highlight animation.
Merge data.list into 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.

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.

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

Example

Required

Description

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.

json

1{2  "success": true,3  "message": "Messages fetched successfully",4  "data": {5    "highlightMessageId": "6a4e...ef5c",6    "list": [7      {8        "_id": "6a4e...ef5c",9        "conversationId": "6a4e...ef5c",10        "sender": {11          "_id": "6a4e...ef5c",12          "name": "John Doe"13        },14        "isSystemMessage": false,15        "content": "Hi",16        "type": "text",17        "isEdited": false,18        "isForwarded": false,19        "status": "read",20        "readBy": [21          {22            "_id": "6a4e...ef5c",23            "name": "Jane Doe"24          }25        ],26        "starredBy": [],27        "deletedFor": [],28        "isDeletedForEveryone": false,29        "reactions": [],30        "createdAt": "2026-03-11T05:07:49.051Z",31        "updatedAt": "2026-03-11T05:28:34.875Z",32        "__v": 0,33        "isLoggedUserStarred": false,34        "isPinnedMessage": false35      }36    ]37  },38  "error": null39}

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

json

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

HTTP 404 Not Found - Message missing

json

1{2  "success": false,3  "message": "Message not found",4  "data": null,5  "error": "Message not found"6}

HTTP 404 Not Found - Conversation missing

json

1{2  "success": false,3  "message": "Conversation not found",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Access denied

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

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 _id equals highlightMessageId and apply a temporary highlight animation.
Merge data.list into 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.