SMS and Call Spam Reporting

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


To report SMS messages and calls, the user must enable an Unwanted Communication extension in the Settings app. They can only enable one Unwanted Communication 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 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 prepare(for:) method.

  3. Presents the controller to the user.

Use your ILClassificationUIExtensionViewController subclass to gather data from the user. Override the prepare(for:) method to configure your controller.

The system provides a Cancel and 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 isReadyForClassificationResponse property to true.

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 classificationResponse(for:) 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 classificationResponse(for:) 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.

The system takes different actions based on the response you return. For ILClassificationAction.none, 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 ILClassificationAction.reportNotJunk or ILClassificationAction.reportJunk, the system generates an SMS message based on your response’s action and userInfo properties. The message’s destination is set by the ILClassificationExtensionSMSReportDestination key in your extension’s Info.plist file. The system then displays the SMS message to the user. The user can either send or cancel the message. Finally, the system dismisses the SMS message and your view controller (Figure 5).

Figure 5

Reported but not blocked

An illustration showing the workflow for reportNotJunk or reportJunk.

For ILClassificationAction.reportJunkAndBlockSender, the system generates and displays an SMS message, just like the ILClassificationAction.reportJunk action. However, after dismissing the SMS message, 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

class ILClassificationUIExtensionViewController

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



class ILCommunication

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

class ILMessageCommunication

A concrete subclass representing a SMS message.

class ILCallCommunication

A concrete subclass representing a phone call.



class ILClassificationRequest

The abstract superclass for classification requests.

class ILMessageClassificationRequest

A classification request for SMS messages.

class ILCallClassificationRequest

A classification request for phone calls.



class ILClassificationResponse

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

enum ILClassificationAction

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


Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software