SMS and Call Spam Reporting

Create an app extension that lets users report unwanted SMS messages and calls as junk.


To report SMS messages and calls as spam, the user must enable an Unwanted Communication Reporting extension, called an SMS/Call Reporting extension in the Settings app (see Settings > Phone > SMS/Call Reporting). The user can only enable one Unwanted Communication Reporting extension at a time.

In order to report calls, the user swipes left on an item in the Recents list and selects Report. For SMS messages, they press the Report Messages button when it appears in the Messages transcript. Users can also select messages by long-pressing a message and selecting additional messages, then selecting Report Messages.

When the user reports an SMS message or call, the system launches your Unwanted Communication Reporting extension. Your extension gathers additional information from the user, before deciding whether to report or block the number, as shown in Figure 1.

Figure 1

Gathering additional information from the user

An illustration showing the system instantiating and displaying your view controller in response to the user reporting an SMS message or call.

Specifically, the system:

  1. Instantiates your extension’s ILClassificationUIExtensionViewController subclass.

  2. Calls your controller’s prepareForClassificationRequest: method.

  3. Presents the controller to the user.

Use your ILClassificationUIExtensionViewController subclass to gather data from the user. Override the prepareForClassificationRequest: method to configure your controller.

Cancel or Complete the Report

The system provides a Cancel and a Done button for the controller. By default, the Done button is disabled. As soon as the user has entered all the information you require, enable the Done button by setting the view controller’s readyForClassificationResponse property to YES.

If the user presses the Cancel button, the system dismisses your view controller, as shown in Figure 2.

Figure 2

Canceling the view controller

An illustration showing the user cancelling your view controller.

If the user presses Done, the system calls your view controller’s classificationResponseForRequest: method, passing in an ILClassificationRequest object (Figure 3).

Figure 3

Acting on the user’s information

An illustration showing the user tapping the Done button after entering all the required information in your user interface.

Override the classificationResponseForRequest: method to return a ILClassificationResponse based on the data the user has entered and information abut the SMS message or call from the request object.

Choose a Response

The system takes different actions based on the response. For ILClassificationActionNone, the system dismisses your view controller, but doesn’t take any other action, as shown in Figure 4.

Figure 4

No action taken

An illustration showing the workflow for none.

For ILClassificationActionReportNotJunk or ILClassificationActionReportJunk, the system generates a report based on your response’s action and userInfo properties and then posts it to a network endpoint or sends it via an SMS message, depending on the keys specified in your extension’s Info.plist file.

To send a response over the network connection, you must add an associated domain to your extension. For general instructions, see Supporting Associated Domains in Your App. Note that you must use classificationreport instead of webcredentials when specifying the domains. You must also specify the network endpoint’s address using the ILClassificationExtensionNetworkReportDestination key in your extension’s Info.plist file.

To send your response using SMS, specify a fully qualified destination telephony number using the ILClassificationExtensionSMSReportDestination key in your extension’s Info.plist file. When your app uses this report path, the system displays the SMS message to give the user the opportunity to send or cancel the message.

When the report step is complete, the system dismisses your view controller and any view controllers related to it (see Figure 5).

Figure 5

Reported but not blocked

An illustration showing the workflow for reportNotJunk or reportJunk.

For ILClassificationActionReportJunkAndBlockSender, the system responds just like in the ILClassificationActionReportJunk action. However, after the report step, the system presents an alert letting the user know the number will be blocked. Finally, the system blocks the SMS or call number, and dismisses your view controller as shown in Figure 6.

Figure 6

Reported and blocked

An illustration showing the workflow for reportJunkAndBlockSender.

Blocked numbers are added to the device’s Blocked Contact list. Users can manage this list in the Settings app.

Finally, to protect user privacy, the system always deletes your extension’s container after your extension terminates. For more information, see About the iOS File System.


App Extension


The superclass for an Unwanted Communication Reporting extension’s principal view controller.



An abstract superclass representing a message or call to the user.


A concrete subclass representing a SMS message.


A concrete subclass representing a phone call.



The abstract superclass for classification requests.


A classification request for SMS messages.


A classification request for phone calls.



A response object that tells the system how to handle the reported communications.


The actions the system can take in response to the reported communication.