Search Messages

Required scope: messages-read

Full-text search over messages in the chats the requesting user is a member of. Searches message text (including translations), poll questions, and file attachment titles. filter[chat_ids] can only narrow the searched chats — chats the user is not a member of are always excluded. filter[include_threads] additionally searches the threads of chats the user is a member of.

At least one of filter[query], filter[chat_ids], filter[user_ids], filter[start_date], filter[end_date], or filter[relative_date_duration] is required.

Matched terms in highlight fields are wrapped in <pronto_hl> tags. Results paginate forward only: pass cursors.next (or follow links.next) as the cursor parameter to fetch the next page.

Possible Errors

See errors for more information.

INVALID_REQUEST - No search filter was provided, or the cursor is invalid.

Query Parameters

filter[query]
Type: string

Full-text search query. Supports - for negation and quoted phrases.
filter[search_type]
Type: "messages" or "files"enum

Search message content (messages) or file attachment titles (files).
filter[chat_ids]
Type: string

Comma-separated chat ids to narrow the search to. Chats the user is not a member of are ignored.
filter[user_ids]
Type: string

Comma-separated user ids; only messages sent by these users match.
filter[include_threads]
Type: boolean

Also search the threads of chats the user is a member of.
filter[start_date]
Type: stringFormat: date

Only messages created on or after this date.
filter[end_date]
Type: stringFormat: date

Only messages created on or before this date.
filter[relative_date_duration]
Type: string

ISO-8601 duration (e.g. P30D) restricting results to the recent period. Overrides start_date/end_date.
sort
Type: "relevance" or "-created_at" or "created_at"enum

Result ordering.
page[size]
Type: integer
min:
1
max:
50

Integer numbers.
cursor
Type: string

Pagination cursor from a previous response’s cursors.next.

Responses

application/json
application/json
application/json
application/json

get/messages/search

curl 'https://api.pronto.io/api/messages/search?filter%5Bsearch_type%5D=messages&filter%5Binclude_threads%5D=false&sort=relevance&page%5Bsize%5D=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "data": {
    "results": [
      {
        "message_id": 1,
        "message": {
          "id": 46498515,
          "parent_id": 46498515,
          "user_id": 123456,
          "chat_id": 654321,
          "text": "Hello, world!",
          "edited_version": 0,
          "edited_at": "2022-08-24T22:38:51+00:00",
          "created_at": "2021-07-22T18:05:53Z",
          "updated_at": "2021-07-22T18:05:53Z",
          "language": null,
          "system_event": null,
          "system_message_parts": null,
          "everyone_mentioned": true,
          "location_lat": null,
          "location_long": null,
          "location_accuracy": null,
          "meeting_id": null,
          "poll_id": null,
          "task_id": null,
          "resource_id": null,
          "thread_id": null,
          "conversation_id": 46498515,
          "user": {
            "id": 123456,
            "external_id": "d747948384aac79d4b9c88129e4835d5",
            "first_name": "John",
            "last_name": "Smith",
            "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
            "phone": "+18015551234",
            "email": "user@example.com",
            "role": "user",
            "is_online": true,
            "last_presence_at": "2026-09-23T18:05:53Z",
            "locked": false,
            "welcome_sent_at": "2021-07-22T18:05:54Z",
            "deactivated_at": "2021-07-23T18:55:53Z",
            "created_at": "2021-07-22T18:05:53Z",
            "updated_at": "2021-07-22T18:05:53Z"
          },
          "mentions": [
            {
              "id": 123456,
              "external_id": "d747948384aac79d4b9c88129e4835d5",
              "first_name": "John",
              "last_name": "Smith",
              "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
              "phone": "+18015551234",
              "email": "user@example.com",
              "role": "user",
              "is_online": true,
              "last_presence_at": "2026-09-23T18:05:53Z",
              "locked": false,
              "welcome_sent_at": "2021-07-22T18:05:54Z",
              "deactivated_at": "2021-07-23T18:55:53Z",
              "created_at": "2021-07-22T18:05:53Z",
              "updated_at": "2021-07-22T18:05:53Z"
            }
          ],
          "reactions": [
            {
              "message_id": 1,
              "emoji": "string",
              "emoji_base": null,
              "count": 1,
              "users": [
                1
              ]
            }
          ],
          "meeting": {
            "id": 1,
            "chat_id": 1,
            "status": null,
            "ended_at": null,
            "duration": null,
            "captions_enabled": true,
            "users": [
              1
            ],
            "users_count": 1,
            "streaming_users": [
              1
            ],
            "streaming_users_count": 1,
            "host_id": null,
            "host": {
              "id": 123456,
              "external_id": "d747948384aac79d4b9c88129e4835d5",
              "first_name": "John",
              "last_name": "Smith",
              "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
              "phone": "+18015551234",
              "email": "user@example.com",
              "role": "user",
              "is_online": true,
              "last_presence_at": "2026-09-23T18:05:53Z",
              "locked": false,
              "welcome_sent_at": "2021-07-22T18:05:54Z",
              "deactivated_at": "2021-07-23T18:55:53Z",
              "created_at": "2021-07-22T18:05:53Z",
              "updated_at": "2021-07-22T18:05:53Z"
            },
            "ended_by": {
              "id": 123456,
              "external_id": "d747948384aac79d4b9c88129e4835d5",
              "first_name": "John",
              "last_name": "Smith",
              "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
              "phone": "+18015551234",
              "email": "user@example.com",
              "role": "user",
              "is_online": true,
              "last_presence_at": "2026-09-23T18:05:53Z",
              "locked": false,
              "welcome_sent_at": "2021-07-22T18:05:54Z",
              "deactivated_at": "2021-07-23T18:55:53Z",
              "created_at": "2021-07-22T18:05:53Z",
              "updated_at": "2021-07-22T18:05:53Z"
            },
            "archives": [
              {
                "id": 1,
                "meeting_id": 1,
                "status": null,
                "started_at": "2026-10-28T21:07:37.168Z",
                "ended_at": null,
                "duration": null,
                "start_user_id": null,
                "end_user_id": null,
                "file_size": null,
                "url": null,
                "created_at": "2026-10-28T21:07:37.168Z",
                "updated_at": "2026-10-28T21:07:37.168Z"
              }
            ],
            "created_at": "2026-10-28T21:07:37.168Z",
            "updated_at": "2026-10-28T21:07:37.168Z"
          },
          "poll": {
            "id": 1,
            "chat_id": 1,
            "user_id": 1,
            "user": {
              "id": 123456,
              "external_id": "d747948384aac79d4b9c88129e4835d5",
              "first_name": "John",
              "last_name": "Smith",
              "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
              "phone": "+18015551234",
              "email": "user@example.com",
              "role": "user",
              "is_online": true,
              "last_presence_at": "2026-09-23T18:05:53Z",
              "locked": false,
              "welcome_sent_at": "2021-07-22T18:05:54Z",
              "deactivated_at": "2021-07-23T18:55:53Z",
              "created_at": "2021-07-22T18:05:53Z",
              "updated_at": "2021-07-22T18:05:53Z"
            },
            "question": "string",
            "language": "string",
            "closed": true,
            "closes_at": "2026-10-28T21:07:37.168Z",
            "allows_multiple_votes": true,
            "auto_pinned": true,
            "reveal_timing": "always",
            "created_at": "2026-10-28T21:07:37.168Z",
            "updated_at": "2026-10-28T21:07:37.168Z",
            "options": [
              {
                "id": 1,
                "poll_id": 1,
                "text": "string",
                "vote_count": 1,
                "voted": true,
                "created_at": "2026-10-28T21:07:37.168Z",
                "updated_at": "2026-10-28T21:07:37.168Z"
              }
            ]
          },
          "resource": {
            "id": 1,
            "title": null,
            "snippet": null,
            "url": "string",
            "thumbnail_url": null,
            "thumbnail_height": null,
            "thumbnail_width": null,
            "created_at": "2026-10-28T21:07:37.168Z",
            "updated_at": "2026-10-28T21:07:37.168Z"
          },
          "task": {
            "id": 1,
            "chat_id": null,
            "user_id": 1,
            "user": {
              "id": 123456,
              "external_id": "d747948384aac79d4b9c88129e4835d5",
              "first_name": "John",
              "last_name": "Smith",
              "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
              "phone": "+18015551234",
              "email": "user@example.com",
              "role": "user",
              "is_online": true,
              "last_presence_at": "2026-09-23T18:05:53Z",
              "locked": false,
              "welcome_sent_at": "2021-07-22T18:05:54Z",
              "deactivated_at": "2021-07-23T18:55:53Z",
              "created_at": "2021-07-22T18:05:53Z",
              "updated_at": "2021-07-22T18:05:53Z"
            },
            "title": "string",
            "notes": null,
            "assignee_user_id": null,
            "assignee_user": {
              "id": 123456,
              "external_id": "d747948384aac79d4b9c88129e4835d5",
              "first_name": "John",
              "last_name": "Smith",
              "profile_pic_url": "https://somewhere.pronto.io/files/user/555/profilepic?pronto_time=-62169984000",
              "phone": "+18015551234",
              "email": "user@example.com",
              "role": "user",
              "is_online": true,
              "last_presence_at": "2026-09-23T18:05:53Z",
              "locked": false,
              "welcome_sent_at": "2021-07-22T18:05:54Z",
              "deactivated_at": "2021-07-23T18:55:53Z",
              "created_at": "2021-07-22T18:05:53Z",
              "updated_at": "2021-07-22T18:05:53Z"
            },
            "due_at": "2026-10-28T21:07:37.168Z",
            "reminder_local_at": null,
            "completed_at": null,
            "created_at": "2026-10-28T21:07:37.168Z",
            "updated_at": "2026-10-28T21:07:37.168Z",
            "attachments": [
              {
                "title": "string",
                "file_size": 123456,
                "url": "https://pronto.io/files/1/123456789",
                "created_at": "2021-07-30T22:22:47Z",
                "updated_at": "2021-07-30T22:22:47Z"
              }
            ]
          },
          "thread": {
            "id": 4562456,
            "external_id": null,
            "title": "My Chat Group",
            "category_id": null,
            "is_dm": true,
            "is_thread": true,
            "parent_chat_id": null,
            "source_message_id": null,
            "source_message": null,
            "latest_user_message": null,
            "permissions": {
              "create_memberships": "member",
              "update_category": "member",
              "update_title": "member",
              "update_membership_role": "member",
              "delete_own_membership": "member",
              "delete_memberships": "member",
              "record_meetings": "member",
              "create_announcement": "member",
              "create_message": "member",
              "create_meetings": "member",
              "assign_tasks": "member",
              "create_thread": "member",
              "manage_thread": "member",
              "create_thread_message": "member",
              "convert_to_thread": "member"
            },
            "is_supergroup": true,
            "locked": true,
            "pinned_message_id": null,
            "pinned_message_user_id": null,
            "pinned_message_at": null,
            "pinned_message_expires_at": null
          },
          "chat": {
            "id": 4562456,
            "external_id": null,
            "title": "My Chat Group",
            "category_id": null,
            "is_dm": true,
            "is_thread": true,
            "parent_chat_id": null,
            "source_message_id": null,
            "source_message": null,
            "latest_user_message": null,
            "permissions": {
              "create_memberships": "member",
              "update_category": "member",
              "update_title": "member",
              "update_membership_role": "member",
              "delete_own_membership": "member",
              "delete_memberships": "member",
              "record_meetings": "member",
              "create_announcement": "member",
              "create_message": "member",
              "create_meetings": "member",
              "assign_tasks": "member",
              "create_thread": "member",
              "manage_thread": "member",
              "create_thread_message": "member",
              "convert_to_thread": "member"
            },
            "is_supergroup": true,
            "locked": true,
            "pinned_message_id": null,
            "pinned_message_user_id": null,
            "pinned_message_at": null,
            "pinned_message_expires_at": null
          },
          "attachment": {
            "title": "string",
            "file_size": 123456,
            "url": "https://pronto.io/files/1/123456789",
            "created_at": "2021-07-30T22:22:47Z",
            "updated_at": "2021-07-30T22:22:47Z"
          },
          "attachments": [
            {
              "title": "string",
              "file_size": 123456,
              "url": "https://pronto.io/files/1/123456789",
              "created_at": "2021-07-30T22:22:47Z",
              "updated_at": "2021-07-30T22:22:47Z"
            }
          ]
        },
        "highlight": {
          "text": [
            "string"
          ],
          "text_translations": {
            "additionalProperty": [
              "string"
            ]
          },
          "attachments": [
            {
              "id": 1,
              "title": [
                "string"
              ]
            }
          ],
          "poll": {
            "question": [
              "string"
            ],
            "question_translations": {
              "additionalProperty": [
                "string"
              ]
            },
            "options": [
              {
                "id": 1,
                "text": null,
                "text_translations": {
                  "additionalProperty": [
                    "string"
                  ]
                }
              }
            ]
          }
        }
      }
    ],
    "chats_meta": [
      {
        "id": 1,
        "title": null,
        "is_dm": true,
        "is_thread": true,
        "parent_chat_id": null
      }
    ],
    "total_results": 1
  },
  "cursors": {
    "prev": null,
    "next": null
  },
  "links": {
    "next": null
  },
  "meta": {
    "path": "string",
    "per_page": 1
  }
}

Get read receipt counts for a message

Start typing in a chat