Search

[POST] .../v1/chatmessage/search

Searches chat messages by text query and/or date range. Use this method to find messages in one chat by text and/or a date interval, then open a result with ChatMessage/GetAround when context is needed. The request body is required and chat_id must identify the chat when filters are not used; filters metadata exposes chat_id, text and created_date fields and at least text or a date boundary must be provided. The response returns paged ChatMessage records matching the search, with access scoped to the current request user's chat visibility and Staff-private rules. Missing body, missing chat_id, missing text or date criteria, denied access, private-message restrictions, search storage failures and database errors are returned as HTTP 200 ErrorResult business errors.

Request Parameters

Name Type Required Description
filters Array of Filter Optional Optional filters by fields available for this API method.
include_staff_private Boolean Optional Include private Staff messages if permitted.
limit Int32 Optional Maximum number of result items.
offset Int32 Optional Result set offset.

Filterable Fields

Field Type Description
chat_id string Chat UUID. Required filter field.
created_date int
from_date int Creation date lower bound as Unix time in seconds.
query string Search query. Optional when a date range is specified.
text string
to_date int Creation date upper bound as Unix time in seconds.

Request Example

{
  "filters": [
    {
      "field": "chat_id",
      "operator": "Equal",
      "value": "8cdd646d-dbd0-45c0-8f5b-d90a9b000001"
    },
    {
      "field": "text",
      "operator": "Like",
      "value": "invoice"
    },
    {
      "field": "created_date",
      "operator": "GreaterOrEqual",
      "value": "1767220000"
    },
    {
      "field": "created_date",
      "operator": "LessOrEqual",
      "value": "1767225600"
    }
  ],
  "limit": 50,
  "offset": 0
}

Response Parameters

Name Type Description
next_offset Int32 Offset for the next data page.
ok Boolean Indicates whether the request completed successfully.
result Array of ChatMessage Result array.
total Int64 Total number of result items.

Response Example

{
  "ok": true,
  "result": [
    {
      "reply_id": null,
      "replay_text": null,
      "id": "4b9727ec-a389-4274-95b6-069350000001",
      "chat_id": "8cdd646d-dbd0-45c0-8f5b-d90a9b000001",
      "author_entity_type": "User",
      "author_entity_id": 42,
      "author_role": "Staff",
      "author_entity_name": "Alex Carter",
      "author_entity_photo": null,
      "message_type": "Regular",
      "text": "Please review the supplier invoice.",
      "mentions": [],
      "file_ids": [
        321
      ],
      "action_code": null,
      "action_payload": null,
      "actions": null,
      "event_id": "evt-chat-message-0001",
      "external_message_id": "external-message-1001",
      "edited": false,
      "read": false,
      "pinned": true,
      "reactions": [
        {
          "reaction": "like",
          "count": 2,
          "selected": true
        }
      ],
      "recipient_count": 3,
      "read_count": 1,
      "created_date": 1767225600,
      "last_update": 1767225600
    }
  ],
  "next_offset": 50,
  "total": 1
}