iOS Developer Library

Developer

Message UI Framework Reference MFMessageComposeViewController Class Reference

Options
Deployment Target:

On This Page
Language:

MFMessageComposeViewController

An MFMessageComposeViewController object provides a standard interface for composing and sending SMS or MMS messages. Use this view controller to display the standard message composition interface inside your app. Before presenting the interface, populate the fields with the set of initial recipients and the message you want to send. After presenting the interface, the user can edit your initial values before sending the message.

The composition interface does not guarantee the delivery of your message; it only lets you construct the initial message and present it for user approval. The user may opt to cancel the composition interface, in which case the message and its contents are discarded. If the user opts to send the message, the Messages app takes on the responsibility of sending the message.

Figure 1The message composition interface image: ../Art/message_composition_2x.png

An alternate way to compose SMS messages is to create and open a URL that uses the sms scheme. URLs of that type are directed to the Messages app, which uses your URL to configure the message. For information about the structure of sms URLs, see Apple URL Scheme Reference.

Checking the Availability of the Composition Interface

Before presenting the message compose view controller, always call the the canSendText method to see if the current device is configured to send messages. If the user’s device is not set up for the delivery of messages, you can notify the user or simply disable the messaging features in your application. You should not attempt to use this interface if the canSendText method returns NOfalse. If messaging is available, you can also use the canSendAttachments and canSendSubject methods to determine if those specific messaging features are available.

Listing 1Checking the availability of message services

Objective-C

  1. if (![MFMessageComposeViewController canSendText]) {
  2. NSLog(@"Message services are not available.");
  3. }

Swift

  1. if !MFMessageComposeViewController.canSendText() {
  2. print("SMS services are not available")
  3. }

Configuring and Displaying the Composition Interface

After verifying that message services are available, you can create and configure the message composition view controller and then present it like you would any other view controller. Use the methods of this class to specify the message’s recipients and the contents of the message. If attachments or a subject line are supported, you can set values for them as well. Listing 2 shows how to configure the composition interface and present it modally. Always assign a delegate to the messageComposeDelegate property. The delegate is responsible for dismissing the composition interface later. The delegate object must conform to the MFMessageComposeViewControllerDelegate protocol.

Listing 2Configuring and presenting the composition interface

Objective-C

  1. MFMessageComposeViewController* composeVC = [[MFMessageComposeViewController alloc] init];
  2. composeVC.messageComposeDelegate = self;
  3. // Configure the fields of the interface.
  4. composeVC.recipients = @[@"14085551212"];
  5. composeVC.body = @"Hello from California!";
  6. // Present the view controller modally.
  7. [self presentViewController:composeVC animated:YES completion:nil];

Swift

  1. let composeVC = MFMessageComposeViewController()
  2. composeVC.messageComposeDelegate = self
  3. // Configure the fields of the interface.
  4. composeVC.recipients = ["4085551212"]
  5. composeVC.body = "Hello from California!"
  6. // Present the view controller modally.
  7. self.presentViewController(composeVC, animated: true, completion: nil)

The mail compose view controller is not dismissed automatically. When the user taps the buttons to send the email or cancel the interface, the mail compose view controller calls the mailComposeController:didFinishWithResult:error: method of its delegate. Your implementation of that method must dismiss the view controller explicitly, as shown in Listing 3. You can also use this method to check the result of the operation.

Listing 3Dismissing the mail compose view controller

Objective-C

  1. - (void)messageComposeViewController:(MFMessageComposeViewController *)controller
  2. didFinishWithResult:(MessageComposeResult)result {
  3. // Check the result or perform other tasks.
  4. // Dismiss the mail compose view controller.
  5. [self dismissViewControllerAnimated:YES completion:nil];
  6. }

Swift

  1. func messageComposeViewController(controller: MFMessageComposeViewController,
  2. didFinishWithResult result: MessageComposeResult) {
  3. // Check the result or perform other tasks.
  4. // Dismiss the mail compose view controller.
  5. controller.dismissViewControllerAnimated(true, completion: nil)
  6. }

For more information on how to present and dismiss view controllers, see View Controller Programming Guide for iOS.

Detecting Changes to the Availability of Messaging

To be notified of changes to the messaging capabilities of the current device, add an observer to the MFMessageComposeViewControllerTextMessageAvailabilityDidChangeNotification notification. The system delivers that notification to your observer when the status of messaging changes.

  • Returns a Boolean value indicating whether the current device is capable of sending text messages.

    Declaration

    Swift

    class func canSendText() -> Bool

    Objective-C

    + (BOOL)canSendText

    Return Value

    YEStrue if the device can send text messages or NOfalse if it cannot.

    Discussion

    Always call this method before attempting to present the message compose view controller. A device may be unable to send messages if it does not support messaging or if it is not currently configured to send messages. This method applies only to the ability to send text messages via iMessage, SMS, and MMS.

    To be notified of changes in the availability of sending text messages, register as an observer of the MFMessageComposeViewControllerTextMessageAvailabilityDidChangeNotification notification.

    Availability

    Available in iOS 4.0 and later.

  • Indicates whether or not messages can include attachments.

    Declaration

    Swift

    class func canSendAttachments() -> Bool

    Objective-C

    + (BOOL)canSendAttachments

    Return Value

    YEStrue if the device can send attachments in MMS or iMessage messages, or NOfalse otherwise.

    Availability

    Available in iOS 7.0 and later.

  • Indicates whether or not messages can include subject lines, according to the user’s configuration in Settings.

    Declaration

    Swift

    class func canSendSubject() -> Bool

    Objective-C

    + (BOOL)canSendSubject

    Return Value

    YEStrue if the device can include subject lines in messages, or NOfalse otherwise.

    Availability

    Available in iOS 7.0 and later.

  • Indicates whether or not the message can accept a file, with the specified UTI, as an attachment.

    Declaration

    Swift

    class func isSupportedAttachmentUTI(_ uti: String) -> Bool

    Objective-C

    + (BOOL)isSupportedAttachmentUTI:(NSString *)uti

    Parameters

    uti

    The UTI (Uniform Type Identifier) in question. See Uniform Type Identifiers Reference

    Return Value

    YEStrue if a file with the specified UTI can be attached to the message, or NOfalse otherwise.

    Availability

    Available in iOS 7.0 and later.

  • An array of strings containing the initial recipients of the message.

    Declaration

    Swift

    var recipients: [String]?

    Objective-C

    @property(nonatomic, copy) NSArray <NSString *> *recipients

    Discussion

    If you want to provide an initial array of one or more recipients for a message, do so before you display it. After the message is displayed you cannot change the value of this property.

    Each string in the array should contain the phone number of the intended recipient.

    Availability

    Available in iOS 4.0 and later.

  • The initial subject of the message.

    Declaration

    Swift

    var subject: String?

    Objective-C

    @property(nonatomic, copy) NSString *subject

    Discussion

    If you want to provide an initial subject for a message, do so before you display it. After the message is displayed you cannot change the value of this property.

    Availability

    Available in iOS 7.0 and later.

  • body body Property

    The initial content of the message.

    Declaration

    Swift

    var body: String?

    Objective-C

    @property(nonatomic, copy) NSString *body

    Discussion

    If you want to provide initial content in the body of a message, do so before you display it. After the message is displayed you cannot change the value of this property.

    Availability

    Available in iOS 4.0 and later.

  • Returns an array of dictionaries that each describe the properties of an attachment. (read-only)

    Declaration

    Swift

    var attachments: [[NSObject : AnyObject]]? { get }

    Objective-C

    @property(nonatomic, copy, readonly) NSArray <NSDictionary *> *attachments

    Discussion

    Each attachment is described by an NSDictionary object in the attachments array. To retrieve the alternate file name for an attachment from its dictionary, use the MFMessageComposeViewControllerAttachmentAlternateFilename key.

    Availability

    Available in iOS 7.0 and later.

  • Attaches a specified file to the message.

    Declaration

    Swift

    func addAttachmentURL(_ attachmentURL: NSURL, withAlternateFilename alternateFilename: String?) -> Bool

    Objective-C

    - (BOOL)addAttachmentURL:(NSURL *)attachmentURL withAlternateFilename:(NSString *)alternateFilename

    Parameters

    attachmentURL

    The file URL for the attachment. Must not be nil.

    alternateFilename

    If you supply a string here, the message UI uses it for the attachment. Use an alternate filename to better describe the attachment or to make the name more readable.

    OK to use a nil value, in which case the attachment’s actual filename is displayed in the message UI.

    Return Value

    YEStrue if the attachment at the specified URL was successfully added to the message, or NOfalse otherwise.

    Discussion

    You can add zero or more attachments to a message before you display the message to the user. To access information about a message’s attachments, access the attachments property.

    Availability

    Available in iOS 7.0 and later.

  • Attaches arbitrary content to the message.

    Declaration

    Swift

    func addAttachmentData(_ attachmentData: NSData, typeIdentifier uti: String, filename filename: String) -> Bool

    Objective-C

    - (BOOL)addAttachmentData:(NSData *)attachmentData typeIdentifier:(NSString *)uti filename:(NSString *)filename

    Parameters

    attachmentData

    Content in the form of an NSData object to attach to the message. Must not be nil.

    uti

    A valid Uniform Type Identifier (UTI) appropriate for the attachment data. See Uniform Type Identifiers Reference. Must not be nil.

    filename

    The name to present to the user, in the message UI, for the data attachment.

    Return Value

    YEStrue if the attachment data was successfully added to the message, or NOfalse otherwise.

    Discussion

    This method is especially useful when the attachment you want to add to a message does not have a file system representation. This can be the case, for example, for programmatically composed audiovisual content.

    Availability

    Available in iOS 7.0 and later.

  • Disables the camera/attachment button in the message composition view.

    Declaration

    Swift

    func disableUserAttachments()

    Objective-C

    - (void)disableUserAttachments

    Discussion

    In iOS 7.0 and later, call this method to disable the camera/attachment button in the message composition view. In an app linked against an older version of iOS, the camera/attachment button is not available in any case.

    Availability

    Available in iOS 7.0 and later.

Data Types

  • These constants describe the result of the message composition interface.

    Declaration

    Swift

    struct MessageComposeResult : RawRepresentable, Equatable { init(_ rawValue: UInt32) init(rawValue rawValue: UInt32) var rawValue: UInt32 }

    Objective-C

    enum MessageComposeResult { MessageComposeResultCancelled, MessageComposeResultSent, MessageComposeResultFailed }; typedef enum MessageComposeResult MessageComposeResult;

    Constants

    • MessageComposeResultCancelled

      MessageComposeResultCancelled

      The user canceled the composition.

      Available in iOS 4.0 and later.

    • MessageComposeResultSent

      MessageComposeResultSent

      The user successfully queued or sent the message.

      Available in iOS 4.0 and later.

    • MessageComposeResultFailed

      MessageComposeResultFailed

      The user’s attempt to save or send the message was unsuccessful.

      Available in iOS 4.0 and later.

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 4.0 and later.

  • A userInfo dictionary key for the MFMessageComposeViewControllerTextMessageAvailabilityDidChangeNotification notification.

    Declaration

    Swift

    let MFMessageComposeViewControllerTextMessageAvailabilityKey: String

    Objective-C

    NSString *const MFMessageComposeViewControllerTextMessageAvailabilityKey;

    Constants

    • MFMessageComposeViewControllerTextMessageAvailabilityKey

      MFMessageComposeViewControllerTextMessageAvailabilityKey

      The value of this key is an NSNumber object containing a Boolean value. This value matches the result of the canSendText class method.

      Available in iOS 5.0 and later.

  • The URL for the item attached to the message.

    Declaration

    Swift

    let MFMessageComposeViewControllerAttachmentURL: String

    Objective-C

    NSString *const MFMessageComposeViewControllerAttachmentURL;

    Constants

    • MFMessageComposeViewControllerAttachmentURL

      MFMessageComposeViewControllerAttachmentURL

      The URL for the item attached to the message.

      Available in iOS 7.0 and later.

  • The key for the alternate filename for the file-based item attached to the message.

    Declaration

    Swift

    let MFMessageComposeViewControllerAttachmentAlternateFilename: String

    Objective-C

    NSString *const MFMessageComposeViewControllerAttachmentAlternateFilename;

    Constants

    • MFMessageComposeViewControllerAttachmentAlternateFilename

      MFMessageComposeViewControllerAttachmentAlternateFilename

      Use this constant with the attachments property to retrieve the optional, more descriptive name for the attachment to a message.

      Available in iOS 7.0 and later.