> ## Documentation Index > Fetch the complete documentation index at: https://social-b97141fb-auto-generate-llmstxt.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Search messages > Retrieve messages based on search criteria ## OpenAPI ````yaml https://raw.githubusercontent.com/AmityCo/apidocs/refs/heads/develop/bundled.json get /api/v2/search/messages openapi: 3.0.0 info: title: Social+ Cloud SDK description: > ## Using Social+ APIs Our API documentation explains all API endpoints used in Social+ Cloud. All APIs, with the exception of some authentication APIs, require an access token for authentication and authorization. APIs can be used either in Admin or User context. When used in user context, you will only be able to fetch data related to that user only. For Administrators who are using our API documentation in making server-to-server API calls, you need an Admin Access token to connect to the Social+ server. Refer to [this documentation](https://docs.social.plus/console/settings#admin-api-access-token) for the instructions on how to generate an admin access token. All backend endpoints that support Social+ Cloud SDK are included here. To easily differentiate the type of each endpoint, we added a prefix in each endpoint's path. - REST API Endpoint: **`/v1, /v2, /v3, /v4, or /v5 ...`** - Webhook Event: **`/webhook ...`** --- ## **Schema Definitions** This section provides detailed descriptions of the key schemas used in Social+ Cloud. Understanding these schemas is essential for effectively integrating our features into your applications. Each schema entry includes a concise description and highlights its core functionality and relationships within the platform. These definitions will help you grasp the structure and purpose of various components, ensuring a seamless and efficient development experience. ### **User** A User represents an individual who interacts with the Social+ Cloud. Users can create profiles, join communities, post content, comment, react, and engage with other users. ### **Role** A Role defines the permissions and access levels for Users within the Social+ Cloud. Roles can be assigned to manage and moderate content, ensuring a controlled and safe environment for all users. ### **Channel** A Channel is a primary structure used to implement various chat messaging capabilities within an application. Channels serve as containers for Subchannels, enabling a hierarchical organization of conversations. This structure allows developers to manage and navigate different chat threads efficiently. ### **Subchannel** A Subchannel is a subdivision within a Channel for specific conversation threads. Subchannels host all messages and interactions, providing organized discussions within a larger channel. Users can individually create, update, delete, and manage subchannels. Moderation actions, such as banning and muting, are applied at the channel level, affecting all subchannels. ### **ChannelUser** A ChannelUser represents an individual user within a specific Channel. This schema tracks user participation, roles, and permissions within the channel. Each ChannelUser can interact in subchannels, participate in discussions, and engage with other members. Users can be assigned roles with varying permissions, such as admin, moderator, or member, allowing for tailored access and control. Moderation actions like banning or muting a ChannelUser affect their participation across all subchannels within the channel. ### **Message** A Message facilitates real-time communication among channel users. Messages can contain up to 20,000 characters or weigh up to 100KB for custom content. For larger binary data, such as files, it's recommended to upload the data to a cloud storage service like AWS S3 and include the URL in the message. The SDK supports various message types, including text and image, built on a standard message layer. ### **Community** A Community is a feature that allows users to share their posts and comments and engage with each other within the app. Communities provide a dedicated space for discussing specific topics or interests. ### **CommunityUser** A CommunityUser represents an individual user within a specific Community. This schema tracks user participation, roles, and interactions within the community. CommunityUsers can join public or private communities, participate in discussions, and engage with other members. Each user can have different roles with varying permissions, such as admin, moderator, or member, which control their access and actions within the community. Moderation actions, like banning or muting, can be applied to CommunityUsers to maintain a safe and respectful environment. ### **CommunityCategory** A CommunityCategory helps organize and manage communities by categorizing them into specific groups. This categorization allows users to easily sort and filter communities based on their interests or needs. ### **Post** A Post is a piece of content created and shared by a user within a network or community. Posts can include text, images, videos, or other elements. Users can create, view, and interact with posts in a social feed, which can be displayed in chronological order and customized using various settings. Post types supported by Social+ include text, image, video, file, live stream, poll, and custom posts. The parent post serves as a container for text data, while each multimedia element (e.g., image, video) is treated as a separate child post. Both parent and child posts support reactions and comments, allowing users to engage comprehensively with content. ### **Comment** A Comment in Social+ Cloud is a user-generated response to specific content, such as a post or story. Comments enable users to engage in conversations, express thoughts, opinions, and emotions, fostering a sense of community around the content. **Comment Reference Types:** - **Post Type Comment:** Designed for regular posts like text updates, photos, or videos. These comments are associated with the post and displayed beneath it, promoting conversation and interaction. - **Story Type Comment:** Similar to post type comments but associated with stories, driving user engagement and discussion around short-lived content. - **Content Type Comment:** Intended for content-specific such as articles or specialized content, providing a more organized and contextual commenting experience. ### **Reaction** A Reaction is a user interaction on messages, posts, or comments, such as like, dislike, or love. The type of reactions is customizable. Currently, reactions are supported for Posts, Messages, and Comments. **Reaction Reference Types:** - **Comment Reference Type:** Allows users to query reactions on a specific comment, showing how others have responded to it. - **Post Reference Type:** Allows users to query reactions on a specific post, highlighting user engagement with the post. - **Story Reference Type:** Allows users to query reactions on a specific story, showing user reactions to the story. ### **File** A File in Social+ Cloud supports file upload and download, enabling file-sharing within applications. It handles various file types, including images, videos, audio, and documents, with a maximum size of 1 GB. This functionality allows users to share files directly in chats or social feeds, enhancing engagement and interaction. ### **Follow** A Follow schema in Social+ Cloud defines one-directional relationships between users, essential for social networking features. When user A follows user B, user A can see user B's updates in their feed, but user B does not need to reciprocate. This schema helps manage visibility and accessibility of user-generated content in user feeds. --- ## Select Region Endpoint Before making server-to-server API calls, be sure to select the correct API endpoint for your region in the **Servers** dropdown below. version: 4.118.0 servers: - url: https://apix.us.amity.co description: API Endpoint for US Region - url: https://apix.eu.amity.co description: API Endpoint for EU Region - url: https://apix.sg.amity.co description: API Endpoint for SG Region security: [] paths: /api/v2/search/messages: get: tags: - Message summary: Search messages description: Retrieve messages based on search criteria parameters: - name: query in: query required: true description: Keyword for searching schema: type: string minLength: 1 maxLength: 1024 - name: exactMatch in: query required: false description: Flag to indicate exact match schema: type: boolean default: false - name: channelId in: query required: false description: Channel ID to scope the search schema: type: string - name: messageFeedId in: query required: false description: Message Feed ID to scope the search schema: type: string - name: userIds in: query required: false description: Array of user public IDs to filter creators schema: type: array minItems: 1 items: type: string minLength: 1 maxItems: 10 - name: types in: query required: false description: Array of message types to include schema: type: array uniqueItems: true default: - text items: type: string enum: - text - image - video - audio - file maxItems: 10 - name: tags in: query required: false description: Array of tags to include schema: type: array uniqueItems: true items: type: string minLength: 1 maxLength: 30 maxItems: 10 - name: options in: query required: false description: Additional search options schema: type: object properties: limit: type: number minimum: 1 maximum: 100 default: 20 orderBy: type: string default: desc enum: - desc - asc sortBy: type: string enum: - createdAt - relevance default: createdAt token: type: string maxLength: 100 responses: '200': description: Search messages response content: application/json: schema: properties: status: type: string data: type: object properties: messages: type: array items: type: object properties: _id: type: string path: type: string messageId: type: string description: ID of a message. channelId: type: string description: ID of a channel. userId: type: string description: ID of a user. type: type: string enum: - text - image - file - custom - video - audio - imagemap data: type: object description: Body of a message. channelSegment: type: integer description: A sequence number of a message in channel. parentId: type: string description: ID of a parent message. fileId: type: string description: file key on cloud storage. tags: type: array description: List of tags. They will be used for searching. items: type: string metadata: type: object description: Additional properties to support custom fields. flagCount: type: integer description: The number of users that has read this message. hashFlag: type: object description: >- The flag for checking internally that this message is reported or not. properties: bits: type: integer hashes: type: integer hash: type: array items: type: string childrenNumber: type: integer description: A number of comments in this message. reactionsCount: type: integer description: The number of all reactions for this messages. reactions: type: object description: The mapping of reaction with reactionCounter. myReactions: type: array description: >- The list of my reactions to this message. This property will not exist when it is triggered from an event 'message.didUpdate'. items: type: string latestReaction: type: object description: >- The latest reaction. This property will exist when it is triggered from an event 'message.didUpdate'. properties: referenceId: type: string description: ID of a document. referenceType: type: string description: Type of document. reactionName: type: string userId: type: string userDisplayName: type: string reactionId: type: string eventName: type: string createdAt: type: string description: The date/time when a reaction is created. format: date-time isDeleted: type: boolean description: >- A flag to hide a message. Unable to show after hiding. It will be set to true when user deletes a message or a channel of this message is banned. createdAt: type: string description: The date/time when a channel is created. format: date-time updatedAt: type: string description: >- The date/time when a channel of this message is banned or this message is deleted. format: date-time editedAt: type: string description: >- The date/time when a message is deleted or updated. format: date-time mentionees: type: array description: >- The object of the mentions type and user who get a notification for the message. items: type: object properties: type: type: string description: > type: * `user` - need to specific userIds and notification mentions individual user * `channel` - notification mentions all user in channel enum: - user - channel userIds: type: array description: >- Array of UserId. if the mention type is a channel, doesn't send userIds items: type: string userPublicIds: type: array description: Array of UserPublicId. items: type: string userInternalIds: type: array description: Array of UserInternalId. items: type: string messageFeeds: type: array items: type: object properties: messageFeedId: description: The ID of the message feed type: string maxLength: 30 example: a85dca058f5b585f86a29f14 channelId: description: >- Internal ID of the channel that the message feed belongs to type: string maxLength: 30 example: abc665aed9dbb8d036037eeb channelPublicId: description: >- ID of the channel that the message feed belongs to type: string maxLength: 30 example: abc665aed9dbb8d036037eeb channelType: description: >- Type of the channel that the message feed belongs to type: string enum: - broadcast - community - conversation - live example: community name: description: The name of the message feed type: string maxLength: 100 example: text lastMessageId: description: >- The ID of the last message created in the message feed type: string maxLength: 30 example: 9530b11ec8de87db22b06b21 lastMessageTimestamp: description: >- The created timestamp of the the last message created in the message feed type: string format: date-time creatorId: description: Creator's ID type: string maxLength: 30 example: 8aa313c8dbb00af911b07672 path: description: Object path type: string maxLength: 200 example: >- 12cba9779cc479e1fcefd1de/chat/f00ab16cbd27d4a9525aea6d/32b468ae0b1bd0cc7976719d/0a003482f0ac53a71e7c9239 childCount: description: The number of messages inside the message feed type: number format: int32 isDeleted: description: Soft delete flag type: boolean default: false editedAt: description: The edited timestamp of the message feed data type: string format: date-time createdAt: description: The created timestamp of the message feed type: string format: date-time updatedAt: description: The updated timestamp of the message feed type: string format: date-time messagePreviewId: type: string description: >- ID of a message preview. Depends on network settings. if disabled will be null. required: - messageFeedId - channelId - channelPublicId - channelType - name - creatorId - path - childCount - isDeleted - createdAt - updatedAt channels: type: array items: type: object properties: _id: type: string path: type: string channelId: type: string description: ID of a channel. channelInternalId: type: string channelPublicId: type: string isDistinct: type: boolean metadata: type: object description: Additional properties to support custom fields. type: type: string enum: - standard - private - conversation - broadcast - community - live description: | Channel Type: * `standard` - Standard channel (deprecated) is public everyone can search and join this channel. * `private` - Private channel (deprecated) is private only member can search and found this channel. * `conversation` - Conversation channel is direct chat created by both users. * `broadcast` - Broadcast channel is send message by admin only * `community` - rename from Standard channel * `live` - rename from Private channel tags: type: array description: List of tags. They will be used for searching. items: type: string isMuted: type: boolean description: >- Is this channel muted? (Computed by using muteTimeout). isRateLimited: type: boolean description: >- Is this channel limited sending rate? (Computed by using muteTimeout). muteTimeout: type: string description: The date/time to suppress muteness. format: date-time rateLimit: type: integer description: Number of messages within rate limit. rateLimitWindow: type: integer description: >- Waiting time interval before reset rateLimit to 0. rateLimitTimeout: type: string description: >- The date/time to suppress limitation of sending rate. format: date-time displayName: type: string description: Channel name for displaying. messageAutoDeleteEnabled: type: boolean description: >- Is message in this channel will be deleted when the user flagged until flag limit? autoDeleteMessageByFlagLimit: type: number description: >- Number of flags that will force a message to be deleted automatically. memberCount: type: integer description: Number of members in channel. messageCount: type: integer description: Number of messages in channel. lastActivity: type: string description: >- The date/time when a user last did something related to the channel such as add/remove members . format: date-time createdAt: type: string description: The date/time when a channel is created. format: date-time updatedAt: type: string description: The date/time when a channel is updated. format: date-time avatarFileId: type: string isDeleted: type: boolean default: false description: A flag to deleted a channel. messagePreviewId: type: string description: >- ID of a message preview. Depends on network settings. if disabled will be null. isPublic: type: boolean description: A flag to public or private a channel. notificationMode: type: string enum: - default - silent - subscribe description: | Notification Mode: * `default` - Auto register push notification. * `silent` - Do not send notification. * `subscribe` - Send notification to subscribed users only. attachedTo: type: object properties: postId: type: string videoStreamId: type: string roomId: type: string required: - channelId - createdAt - updatedAt users: type: array items: type: object properties: _id: type: string description: Private ID of a user. (for real-time event) path: type: string description: Path of a user. (for real-time event) userId: type: string userInternalId: type: string userPublicId: type: string roles: type: array items: type: string permissions: type: array items: type: string enum: - MUTE_CHANNEL - CLOSE_CHANNEL - EDIT_CHANNEL - EDIT_CHANNEL_RATELIMIT - EDIT_MESSAGE - DELETE_MESSAGE - BAN_USER_FROM_CHANNEL - MUTE_USER_INSIDE_CHANNEL - ADD_CHANNEL_USER - REMOVE_CHANNEL_USER - EDIT_CHANNEL_USER - ASSIGN_CHANNEL_USER_ROLE - BAN_USER - EDIT_USER - ASSIGN_USER_ROLE - EDIT_USER_FEED_POST - DELETE_USER_FEED_POST - EDIT_USER_FEED_COMMENT - DELETE_USER_FEED_COMMENT - ADD_COMMUNITY_USER - REMOVE_COMMUNITY_USER - EDIT_COMMUNITY_USER - BAN_COMMUNITY_USER - MUTE_COMMUNITY_USER - EDIT_COMMUNITY - DELETE_COMMUNITY - EDIT_COMMUNITY_POST - DELETE_COMMUNITY_POST - PIN_COMMUNITY_POST - EDIT_COMMUNITY_COMMENT - DELETE_COMMUNITY_COMMENT - ASSIGN_COMMUNITY_USER_ROLE - CREATE_COMMUNITY_CATEGORY - EDIT_COMMUNITY_CATEGORY - DELETE_COMMUNITY_CATEGORY - CREATE_ROLE - EDIT_ROLE - DELETE_ROLE - MANAGE_COMMUNITY_STORY displayName: type: string profileHandle: type: string description: type: string avatarFileId: type: string avatarCustomUrl: type: string flagCount: type: integer hashFlag: type: object properties: bits: type: integer hashes: type: integer hash: type: array items: type: string metadata: type: object isGlobalBan: type: boolean description: Global ban status. Every user can see this flag. isBrand: type: boolean description: Brand user status. createdAt: type: string format: date-time updatedAt: type: string format: date-time isDeleted: type: boolean required: - userId - createdAt - updatedAt files: type: array items: type: object properties: fileId: type: string description: Root file key on cloud storage. fileUrl: type: string description: Http link for download file type: type: string description: File type. enum: - image - file - video accessType: type: string description: >- File access type. `network` type requires authentication to download. enum: - public - network default: public altText: type: string description: Alternative text for the file. maxLength: 180 createdAt: type: string description: The date/time when a file is uploaded. format: date-time updatedAt: type: string description: The date/time when a file is updated. format: date-time attributes: type: object properties: name: type: string description: File name. extension: type: string description: File format. size: type: number description: File size. mimeType: type: string description: File mime-type. metadata: type: object description: File image metadata (width, height etc.). properties: exif: type: object gps: type: object height: type: number width: type: number isFull: type: boolean roles: type: array items: type: object properties: roleId: type: string displayName: type: string updatedAt: type: string description: The date/time when a role is updated or deleted. format: date-time createdAt: type: string description: The date/time when a role is created. format: date-time permissions: type: array items: type: string description: >- The list of permission for this role. https://docs.amity.co/amity-sdk/core-concepts/user/user-permission#permissions isDeleted: type: boolean default: false required: - roleId - permissions - updatedAt - isDeleted totalCount: type: number paging: type: object properties: next: type: string prev: type: string search: type: object properties: query: type: string description: The search query. limit: type: integer description: Limit on the number of results. sortBy: type: string description: >- Sorting criteria (e.g., "relevance" or "createdAt"). orderBy: type: string description: Sorting order (e.g., "desc"). '400': description: Bad Request error. content: application/json: schema: type: object properties: status: type: string code: type: number message: type: string data: type: object properties: detail: oneOf: - type: array items: type: string - type: object example: status: error code: 400000 message: Bad Request. '403': description: Permission denied. content: application/json: schema: type: object properties: status: type: string code: type: number message: type: string data: type: object properties: detail: oneOf: - type: array items: type: string - type: object example: status: error code: 400301 message: User is not a member of a channel '404': description: Resource Not Found error. content: application/json: schema: type: object properties: status: type: string code: type: number message: type: string data: type: object properties: detail: oneOf: - type: array items: type: string - type: object example: status: error code: 400400 message: Resource Not Found. '422': description: Parameters validation error. content: application/json: schema: type: object properties: status: type: string code: type: number message: type: string data: type: object properties: detail: oneOf: - type: array items: type: string - type: object example: status: error code: 500000 message: Parameters validation error '429': description: >- Error due to a client create the same request with the same parameters exceed the number of time that server limit to. content: application/json: schema: type: object properties: status: type: string code: type: number message: type: string data: type: object properties: detail: oneOf: - type: array items: type: string - type: object example: status: error code: 400311 message: RateLimit Exceed. '500': description: Unexpected error. content: application/json: schema: type: object properties: status: type: string code: type: number message: type: string data: type: object properties: detail: oneOf: - type: array items: type: string - type: object example: status: error code: 500000 message: Unexpected error security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer ````