API Reference

Search Messages

Overview

Search message text within a single conversation — for the in-chat find-messages UI, quick filters, and jump-to-result flows inside the messaging client.

Returns a lightweight list of matching messages with content, type, and timestamps. Pair results with Search Message Context to open the thread scrolled to the selected hit.

When to use this endpoint?

Use Search Messages when:

Building the in-conversation search bar or find-in-chat panel.
Filtering messages by free-text query while the user types.
Showing a compact result list before navigating to the full thread context.
Scoping search to the currently open conversationId only.

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.

Response Data

The data.list array contains compact search hits. Each item includes:

Field	Description
_id	Message id. Pass this to Search Message Context when the user taps a result.
content	Message body text that matched the search query.
type	Message type (for example `text`).
status	Delivery/read status (for example `read`).
createdAt / updatedAt	ISO timestamps for when the message was sent and last updated.

GET{baseUrl}/api/{apiVersion}/message/search-messages?conversationId={conversationId}&search=Hello

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
conversationId	{{conversationId}}	Required	Conversation `_id` to scope results to (24-char Mongo ObjectId).
search	Hello	Required	Case-insensitive text search (input is regex-escaped). Matches searchable message fields in this conversation.

Success Response (HTTP 200 OK)

On success, data.list contains matching messages ordered for display in the search results panel.

json

{
  "success": true,
  "message": "Search messages fetched successfully",
  "data": {
    "list": [
      {
        "_id": "6a4e...ef5c",
        "content": "Hi",
        "type": "text",
        "status": "read",
        "createdAt": "2026-03-11T05:56:21.149Z",
        "updatedAt": "2026-03-11T05:56:54.697Z"
      },
      {
        "_id": "6a4e...ef5d",
        "content": "How are you?",
        "type": "text",
        "status": "read",
        "createdAt": "2026-03-11T05:56:18.794Z",
        "updatedAt": "2026-03-11T05:56:54.697Z"
      },
    ]
  },
  "error": null
}

Common Errors

Search 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

json

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

HTTP 404 Not Found — Conversation missing

json

{
  "success": false,
  "message": "Conversation not found",
  "data": null,
  "error": null
}

HTTP 403 Forbidden — Access denied

json

{
  "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` in this tenant.
403 Forbidden	Signed-in user is not a participant or lacks permission to search this conversation.
500 Internal Server Error	An unexpected error occurred while searching messages.

Best Practices

Debounce the search input (300–500 ms) so you do not fire a request on every keystroke.
Require at least two or three characters before searching to reduce noise and API load.
Always pass the open thread's conversationId — search is scoped to one conversation, not the whole tenant.
Highlight matching substrings in the result list using the query text for better scanability.
Always send tenant headers with the chat user Bearer token over HTTPS.

Jump to message in thread

When the user taps a search result, call Search Message Context with the result's _id to load surrounding messages and scroll the thread to the highlighted hit.

Field

Description

_id

Message id. Pass this to Search Message Context when the user taps a result.

content

Message body text that matched the search query.

type

Message type (for example text).

status

Delivery/read status (for example read).

createdAt / updatedAt

ISO timestamps for when the message was sent and last updated.

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

conversationId

Required

Conversation _id to scope results to (24-char Mongo ObjectId).

Hello

Required

Case-insensitive text search (input is regex-escaped). Matches searchable message fields in this conversation.

{ "success": true, "message": "Search messages fetched successfully", "data": { "list": [ { "_id": "6a4e...ef5c", "content": "Hi", "type": "text", "status": "read", "createdAt": "2026-03-11T05:56:21.149Z", "updatedAt": "2026-03-11T05:56:54.697Z" }, { "_id": "6a4e...ef5d", "content": "How are you?", "type": "text", "status": "read", "createdAt": "2026-03-11T05:56:18.794Z", "updatedAt": "2026-03-11T05:56:54.697Z" }, ] }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

404 Not Found

No conversation exists for the given conversationId in this tenant.

403 Forbidden

Signed-in user is not a participant or lacks permission to search this conversation.

500 Internal Server Error

An unexpected error occurred while searching messages.