<!--
{
  "availability" : [
    "iOS: 10.0.0 -",
    "iPadOS: 10.0.0 -",
    "macCatalyst: 13.1.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 3.2.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "SiriKit",
  "identifier" : "/documentation/Intents/INSearchForMessagesIntent",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Intents"
    ],
    "preciseIdentifier" : "c:objc(cs)INSearchForMessagesIntent"
  },
  "title" : "INSearchForMessagesIntent"
}
-->

# INSearchForMessagesIntent

A request to list the messages that match the specified criteria.

```
class INSearchForMessagesIntent
```

## Overview

Siri creates [`INSearchForMessagesIntent`](/documentation/Intents/INSearchForMessagesIntent) objects when the user asks to see sent or received messages. You must implement this intent to support the reading of messages by Siri. This intent object contains the values for you to match when searching the user’s messages. Users can search for messages involving a specific person, messages with specific sent or received dates, or messages containing specific terms. When performing the search, use only the provided parameters, and ignore any that have no values.

To handle this intent, the handler object in your Intents extension must adopt the [`INSearchForMessagesIntentHandling`](/documentation/Intents/INSearchForMessagesIntentHandling) protocol. Your handler confirms the request and creates an [`INSearchForMessagesIntentResponse`](/documentation/Intents/INSearchForMessagesIntentResponse) object with the results of the search. For successful searches, Siri offers the user a way to launch your app and see the results.

> Important:
> To implement support for this intent fully, you must also implement support for the ``doc://com.apple.sirikit/documentation/Intents/INSetMessageAttributeIntent`` class. After reading messages that your search returns, Siri marks them as read by modifying the attributes of the messages using that intent class. For more information about supporting the set message attribute intent, see ``doc://com.apple.sirikit/documentation/Intents/INSetMessageAttributeIntent``.

To allow a user wearing AirPods to automatically hear messages, you must implement both [`INSearchForMessagesIntent`](/documentation/Intents/INSearchForMessagesIntent) and [`INSendMessageIntent`](/documentation/Intents/INSendMessageIntent). Add <doc://com.apple.documentation/documentation/UserNotifications/UNAuthorizationOptions/announcement> to the options when calling <doc://com.apple.documentation/documentation/UserNotifications/UNUserNotificationCenter/requestAuthorization(options:completionHandler:)>. Finally, add <doc://com.apple.documentation/documentation/UserNotifications/UNNotificationCategoryOptions/allowAnnouncement> to the category option and [`INSearchForMessagesIntent`](/documentation/Intents/INSearchForMessagesIntent) to the category intent identifier.

### Additional Intent Attributes

Additional attributes of this intent object include the following:

|Attribute               |Description                                                           |
|------------------------|----------------------------------------------------------------------|
|Supported by            |Siri Intents                                                          |
|Requires unlocked device|Yes, unless Show Previews is in an enabled state on the user’s device.|

Apps can optionally ask the user to unlock the device before handling this intent. To require unlocking of the device, include the name of this class in the `IntentsRestrictedWhileLocked` key of your Intents extension’s `Info.plist` file.

## Topics

### Creating the Intent Object

[`-  initWithRecipients:senders:searchTerms:attributes:dateTimeRange:identifiers:notificationIdentifiers:speakableGroupNames:conversationIdentifiers:`](/documentation/Intents/INSearchForMessagesIntent/init(recipients:senders:searchTerms:attributes:dateTime:identifiers:notificationIdentifiers:speakableGroupNames:conversationIdentifiers:))

Creates a search messages intent object with the specified search criteria.

### Getting the Senders and Recipients

[`recipients`](/documentation/Intents/INSearchForMessagesIntent/recipients)

The contacts who are the recipients of the messages.

[`recipientsOperator`](/documentation/Intents/INSearchForMessagesIntent/recipientsOperator)

The operator that defines how to use the recipients in the search criteria.

[`senders`](/documentation/Intents/INSearchForMessagesIntent/senders)

The senders to include or exclude when you search for messages.

[`sendersOperator`](/documentation/Intents/INSearchForMessagesIntent/sendersOperator)

The operator that defines how to use the senders in the search criteria.

[`speakableGroupNames`](/documentation/Intents/INSearchForMessagesIntent/speakableGroupNames)

The names of any groups associated with the message.

[`speakableGroupNamesOperator`](/documentation/Intents/INSearchForMessagesIntent/speakableGroupNamesOperator)

The operator that defines how to use the group names in the search criteria.

### Getting the Search Criteria

[`searchTerms`](/documentation/Intents/INSearchForMessagesIntent/searchTerms)

The terms to look for in the messages.

[`searchTermsOperator`](/documentation/Intents/INSearchForMessagesIntent/searchTermsOperator)

The operator that defines how to use the set of terms in the search criteria.

[`dateTimeRange`](/documentation/Intents/INSearchForMessagesIntent/dateTimeRange)

The range of dates in which to search for messages.

[`attributes`](/documentation/Intents/INSearchForMessagesIntent/attributes)

The attributes that must be present on a message to yield a match.

### Specifying Message Identifiers

[`identifiers`](/documentation/Intents/INSearchForMessagesIntent/identifiers)

The message identifiers to locate in your search.

[`identifiersOperator`](/documentation/Intents/INSearchForMessagesIntent/identifiersOperator)

The operator that defines how to use the identifiers in the search criteria.

[`conversationIdentifiers`](/documentation/Intents/INSearchForMessagesIntent/conversationIdentifiers)

The conversation identifiers to locate in your search.

[`conversationIdentifiersOperator`](/documentation/Intents/INSearchForMessagesIntent/conversationIdentifiersOperator)

The operator that defines how to use the conversation identifiers in the search criteria.

[`notificationIdentifiers`](/documentation/Intents/INSearchForMessagesIntent/notificationIdentifiers)

The notification identifiers to locate in your search.

[`notificationIdentifiersOperator`](/documentation/Intents/INSearchForMessagesIntent/notificationIdentifiersOperator)

The operator that defines how to use the notification identifiers in the search criteria.

### Deprecated Symbols

[`init(recipients:senders:searchTerms:attributes:dateTimeRange:identifiers:notificationIdentifiers:speakableGroupNames:)`](/documentation/Intents/INSearchForMessagesIntent/init(recipients:senders:searchTerms:attributes:dateTimeRange:identifiers:notificationIdentifiers:speakableGroupNames:))

Creates a *search messages* intent object with the specified search criteria.

[`init(recipients:senders:searchTerms:attributes:dateTimeRange:identifiers:notificationIdentifiers:groupNames:)`](/documentation/Intents/INSearchForMessagesIntent/init(recipients:senders:searchTerms:attributes:dateTimeRange:identifiers:notificationIdentifiers:groupNames:))

Creates a *search messages* intent object with the specified search criteria.

[`groupNames`](/documentation/Intents/INSearchForMessagesIntent/groupNames)

The names of any groups associated with the message.

[`groupNamesOperator`](/documentation/Intents/INSearchForMessagesIntent/groupNamesOperator)

The operator that defines how to use the group names in the search criteria.

## Relationships

### Conforms To

[`INIntentSetImageKeyPath`](/documentation/Intents/INIntentSetImageKeyPath)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`NSCopying`](/documentation/Foundation/NSCopying)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Equatable`](/documentation/Swift/Equatable)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`NSCoding`](/documentation/Foundation/NSCoding)

### Inherits From

[`INIntent`](/documentation/Intents/INIntent)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)