Android APIs
public final class

SmsManager

extends Object
java.lang.Object
   ↳ android.telephony.SmsManager

Class Overview

Manages SMS operations such as sending data, text, and pdu SMS messages. Get this object by calling the static method getDefault().

For information about how to behave as the default SMS app on Android 4.4 (API level 19) and higher, see Telephony.

Summary

Constants
String EXTRA_MMS_DATA Intent extra name for MMS sending result data in byte array type
String EXTRA_MMS_HTTP_STATUS Intent extra name for HTTP status code for MMS HTTP failure in integer type
String MMS_CONFIG_ALIAS_ENABLED Whether alias is enabled (boolean type)
String MMS_CONFIG_ALIAS_MAX_CHARS Max alias character count (int type)
String MMS_CONFIG_ALIAS_MIN_CHARS Min alias character count (int type)
String MMS_CONFIG_ALLOW_ATTACH_AUDIO Whether audio is allowed to be attached for MMS messages (boolean type)
String MMS_CONFIG_APPEND_TRANSACTION_ID Whether to append transaction id to MMS WAP Push M-Notification.ind's content location URI when constructing the download URL of a new MMS (boolean type)
String MMS_CONFIG_EMAIL_GATEWAY_NUMBER Email gateway number (String type)
String MMS_CONFIG_GROUP_MMS_ENABLED Whether group MMS is enabled for the current carrier (boolean type)
String MMS_CONFIG_HTTP_PARAMS A list of HTTP headers to add to MMS HTTP request, separated by "|" (String type)
String MMS_CONFIG_HTTP_SOCKET_TIMEOUT MMS HTTP socket timeout in milliseconds (int type)
String MMS_CONFIG_MAX_IMAGE_HEIGHT Max MMS image height (int type)
String MMS_CONFIG_MAX_IMAGE_WIDTH Max MMS image width (int type)
String MMS_CONFIG_MAX_MESSAGE_SIZE Max MMS message size in bytes (int type)
String MMS_CONFIG_MESSAGE_TEXT_MAX_SIZE Max message text size (int type)
String MMS_CONFIG_MMS_DELIVERY_REPORT_ENABLED Whether MMS delivery report is enabled (boolean type)
String MMS_CONFIG_MMS_ENABLED Whether MMS is enabled for the current carrier (boolean type)
String MMS_CONFIG_MMS_READ_REPORT_ENABLED Whether MMS read report is enabled (boolean type)
String MMS_CONFIG_MULTIPART_SMS_ENABLED Whether multipart SMS is enabled (boolean type)
String MMS_CONFIG_NAI_SUFFIX The suffix to append to the NAI header value for MMS HTTP request (String type)
String MMS_CONFIG_NOTIFY_WAP_MMSC_ENABLED If this is enabled, M-NotifyResp.ind should be sent to the WAP Push content location instead of the default MMSC (boolean type)
String MMS_CONFIG_RECIPIENT_LIMIT Limit of recipients of MMS messages (int type)
String MMS_CONFIG_SEND_MULTIPART_SMS_AS_SEPARATE_MESSAGES Whether multipart SMS should be sent as separate messages
String MMS_CONFIG_SHOW_CELL_BROADCAST_APP_LINKS If true, show the cell broadcast (amber alert) in the SMS settings.
String MMS_CONFIG_SMS_DELIVERY_REPORT_ENABLED Whether SMS delivery report is enabled (boolean type)
String MMS_CONFIG_SMS_TO_MMS_TEXT_LENGTH_THRESHOLD Some carriers require SMS to be converted into MMS when text length reaches this threshold (int type)
String MMS_CONFIG_SMS_TO_MMS_TEXT_THRESHOLD When the number of parts of a multipart SMS reaches this threshold, it should be converted into an MMS (int type)
String MMS_CONFIG_SUBJECT_MAX_LENGTH Max message subject length (int type)
String MMS_CONFIG_SUPPORT_MMS_CONTENT_DISPOSITION Whether content-disposition field should be expected in an MMS PDU (boolean type)
String MMS_CONFIG_UA_PROF_TAG_NAME The name of the UA Prof URL HTTP header for MMS HTTP request (String type)
String MMS_CONFIG_UA_PROF_URL The UA Profile URL header value for MMS HTTP request (String type)
String MMS_CONFIG_USER_AGENT The User-Agent header value for MMS HTTP request (String type)
int MMS_ERROR_CONFIGURATION_ERROR
int MMS_ERROR_HTTP_FAILURE
int MMS_ERROR_INVALID_APN
int MMS_ERROR_IO_ERROR
int MMS_ERROR_NO_DATA_NETWORK
int MMS_ERROR_RETRY
int MMS_ERROR_UNABLE_CONNECT_MMS
int MMS_ERROR_UNSPECIFIED
int RESULT_ERROR_GENERIC_FAILURE Generic failure cause
int RESULT_ERROR_NO_SERVICE Failed because service is currently unavailable
int RESULT_ERROR_NULL_PDU Failed because no pdu provided
int RESULT_ERROR_RADIO_OFF Failed because radio was explicitly turned off
int STATUS_ON_ICC_FREE Free space (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).
int STATUS_ON_ICC_READ Received and read (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).
int STATUS_ON_ICC_SENT Stored and sent (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).
int STATUS_ON_ICC_UNREAD Received and unread (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).
int STATUS_ON_ICC_UNSENT Stored and unsent (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).
Public Methods
ArrayList<String> divideMessage(String text)
Divide a message text into several fragments, none bigger than the maximum SMS message size.
void downloadMultimediaMessage(Context context, String locationUrl, Uri contentUri, Bundle configOverrides, PendingIntent downloadedIntent)
Download an MMS message from carrier by a given location URL
Bundle getCarrierConfigValues()
Get carrier-dependent configuration values.
static SmsManager getDefault()
Get the SmsManager associated with the default subscription id.
static int getDefaultSmsSubscriptionId()
Get default sms subscription id
static SmsManager getSmsManagerForSubscriptionId(int subId)
Get the the instance of the SmsManager associated with a particular subscription id
int getSubscriptionId()
Get the associated subscription id.
void injectSmsPdu(byte[] pdu, String format, PendingIntent receivedIntent)
Inject an SMS PDU into the android application framework.
void sendDataMessage(String destinationAddress, String scAddress, short destinationPort, byte[] data, PendingIntent sentIntent, PendingIntent deliveryIntent)
Send a data based SMS to a specific application port.
void sendMultimediaMessage(Context context, Uri contentUri, String locationUrl, Bundle configOverrides, PendingIntent sentIntent)
Send an MMS message
void sendMultipartTextMessage(String destinationAddress, String scAddress, ArrayList<String> parts, ArrayList<PendingIntent> sentIntents, ArrayList<PendingIntent> deliveryIntents)
Send a multi-part text based SMS.
void sendTextMessage(String destinationAddress, String scAddress, String text, PendingIntent sentIntent, PendingIntent deliveryIntent)
Send a text based SMS.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String EXTRA_MMS_DATA

Added in API level 21

Intent extra name for MMS sending result data in byte array type

Constant Value: "android.telephony.extra.MMS_DATA"

public static final String EXTRA_MMS_HTTP_STATUS

Intent extra name for HTTP status code for MMS HTTP failure in integer type

Constant Value: "android.telephony.extra.MMS_HTTP_STATUS"

public static final String MMS_CONFIG_ALIAS_ENABLED

Added in API level 21

Whether alias is enabled (boolean type)

Constant Value: "aliasEnabled"

public static final String MMS_CONFIG_ALIAS_MAX_CHARS

Added in API level 21

Max alias character count (int type)

Constant Value: "aliasMaxChars"

public static final String MMS_CONFIG_ALIAS_MIN_CHARS

Added in API level 21

Min alias character count (int type)

Constant Value: "aliasMinChars"

public static final String MMS_CONFIG_ALLOW_ATTACH_AUDIO

Added in API level 21

Whether audio is allowed to be attached for MMS messages (boolean type)

Constant Value: "allowAttachAudio"

public static final String MMS_CONFIG_APPEND_TRANSACTION_ID

Added in API level 21

Whether to append transaction id to MMS WAP Push M-Notification.ind's content location URI when constructing the download URL of a new MMS (boolean type)

Constant Value: "enabledTransID"

public static final String MMS_CONFIG_EMAIL_GATEWAY_NUMBER

Added in API level 21

Email gateway number (String type)

Constant Value: "emailGatewayNumber"

public static final String MMS_CONFIG_GROUP_MMS_ENABLED

Added in API level 21

Whether group MMS is enabled for the current carrier (boolean type)

Constant Value: "enableGroupMms"

public static final String MMS_CONFIG_HTTP_PARAMS

Added in API level 21

A list of HTTP headers to add to MMS HTTP request, separated by "|" (String type)

Constant Value: "httpParams"

public static final String MMS_CONFIG_HTTP_SOCKET_TIMEOUT

Added in API level 21

MMS HTTP socket timeout in milliseconds (int type)

Constant Value: "httpSocketTimeout"

public static final String MMS_CONFIG_MAX_IMAGE_HEIGHT

Added in API level 21

Max MMS image height (int type)

Constant Value: "maxImageHeight"

public static final String MMS_CONFIG_MAX_IMAGE_WIDTH

Added in API level 21

Max MMS image width (int type)

Constant Value: "maxImageWidth"

public static final String MMS_CONFIG_MAX_MESSAGE_SIZE

Added in API level 21

Max MMS message size in bytes (int type)

Constant Value: "maxMessageSize"

public static final String MMS_CONFIG_MESSAGE_TEXT_MAX_SIZE

Added in API level 21

Max message text size (int type)

Constant Value: "maxMessageTextSize"

public static final String MMS_CONFIG_MMS_DELIVERY_REPORT_ENABLED

Added in API level 21

Whether MMS delivery report is enabled (boolean type)

Constant Value: "enableMMSDeliveryReports"

public static final String MMS_CONFIG_MMS_ENABLED

Added in API level 21

Whether MMS is enabled for the current carrier (boolean type)

Constant Value: "enabledMMS"

public static final String MMS_CONFIG_MMS_READ_REPORT_ENABLED

Added in API level 21

Whether MMS read report is enabled (boolean type)

Constant Value: "enableMMSReadReports"

public static final String MMS_CONFIG_MULTIPART_SMS_ENABLED

Added in API level 21

Whether multipart SMS is enabled (boolean type)

Constant Value: "enableMultipartSMS"

public static final String MMS_CONFIG_NAI_SUFFIX

Added in API level 21

The suffix to append to the NAI header value for MMS HTTP request (String type)

Constant Value: "naiSuffix"

public static final String MMS_CONFIG_NOTIFY_WAP_MMSC_ENABLED

Added in API level 21

If this is enabled, M-NotifyResp.ind should be sent to the WAP Push content location instead of the default MMSC (boolean type)

Constant Value: "enabledNotifyWapMMSC"

public static final String MMS_CONFIG_RECIPIENT_LIMIT

Added in API level 21

Limit of recipients of MMS messages (int type)

Constant Value: "recipientLimit"

public static final String MMS_CONFIG_SEND_MULTIPART_SMS_AS_SEPARATE_MESSAGES

Added in API level 21

Whether multipart SMS should be sent as separate messages

Constant Value: "sendMultipartSmsAsSeparateMessages"

public static final String MMS_CONFIG_SHOW_CELL_BROADCAST_APP_LINKS

If true, show the cell broadcast (amber alert) in the SMS settings. Some carriers don't want this shown. (Boolean type)

Constant Value: "config_cellBroadcastAppLinks"

public static final String MMS_CONFIG_SMS_DELIVERY_REPORT_ENABLED

Added in API level 21

Whether SMS delivery report is enabled (boolean type)

Constant Value: "enableSMSDeliveryReports"

public static final String MMS_CONFIG_SMS_TO_MMS_TEXT_LENGTH_THRESHOLD

Added in API level 21

Some carriers require SMS to be converted into MMS when text length reaches this threshold (int type)

Constant Value: "smsToMmsTextLengthThreshold"

public static final String MMS_CONFIG_SMS_TO_MMS_TEXT_THRESHOLD

Added in API level 21

When the number of parts of a multipart SMS reaches this threshold, it should be converted into an MMS (int type)

Constant Value: "smsToMmsTextThreshold"

public static final String MMS_CONFIG_SUBJECT_MAX_LENGTH

Added in API level 21

Max message subject length (int type)

Constant Value: "maxSubjectLength"

public static final String MMS_CONFIG_SUPPORT_MMS_CONTENT_DISPOSITION

Added in API level 21

Whether content-disposition field should be expected in an MMS PDU (boolean type)

Constant Value: "supportMmsContentDisposition"

public static final String MMS_CONFIG_UA_PROF_TAG_NAME

Added in API level 21

The name of the UA Prof URL HTTP header for MMS HTTP request (String type)

Constant Value: "uaProfTagName"

public static final String MMS_CONFIG_UA_PROF_URL

Added in API level 21

The UA Profile URL header value for MMS HTTP request (String type)

Constant Value: "uaProfUrl"

public static final String MMS_CONFIG_USER_AGENT

Added in API level 21

The User-Agent header value for MMS HTTP request (String type)

Constant Value: "userAgent"

public static final int MMS_ERROR_CONFIGURATION_ERROR

Added in API level 21

Constant Value: 7 (0x00000007)

public static final int MMS_ERROR_HTTP_FAILURE

Added in API level 21

Constant Value: 4 (0x00000004)

public static final int MMS_ERROR_INVALID_APN

Added in API level 21

Constant Value: 2 (0x00000002)

public static final int MMS_ERROR_IO_ERROR

Added in API level 21

Constant Value: 5 (0x00000005)

public static final int MMS_ERROR_NO_DATA_NETWORK

Constant Value: 8 (0x00000008)

public static final int MMS_ERROR_RETRY

Added in API level 21

Constant Value: 6 (0x00000006)

public static final int MMS_ERROR_UNABLE_CONNECT_MMS

Added in API level 21

Constant Value: 3 (0x00000003)

public static final int MMS_ERROR_UNSPECIFIED

Added in API level 21

Constant Value: 1 (0x00000001)

public static final int RESULT_ERROR_GENERIC_FAILURE

Added in API level 4

Generic failure cause

Constant Value: 1 (0x00000001)

public static final int RESULT_ERROR_NO_SERVICE

Added in API level 4

Failed because service is currently unavailable

Constant Value: 4 (0x00000004)

public static final int RESULT_ERROR_NULL_PDU

Added in API level 4

Failed because no pdu provided

Constant Value: 3 (0x00000003)

public static final int RESULT_ERROR_RADIO_OFF

Added in API level 4

Failed because radio was explicitly turned off

Constant Value: 2 (0x00000002)

public static final int STATUS_ON_ICC_FREE

Added in API level 4

Free space (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).

Constant Value: 0 (0x00000000)

public static final int STATUS_ON_ICC_READ

Added in API level 4

Received and read (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).

Constant Value: 1 (0x00000001)

public static final int STATUS_ON_ICC_SENT

Added in API level 4

Stored and sent (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).

Constant Value: 5 (0x00000005)

public static final int STATUS_ON_ICC_UNREAD

Added in API level 4

Received and unread (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).

Constant Value: 3 (0x00000003)

public static final int STATUS_ON_ICC_UNSENT

Added in API level 4

Stored and unsent (TS 51.011 10.5.3 / 3GPP2 C.S0023 3.4.27).

Constant Value: 7 (0x00000007)

Public Methods

public ArrayList<String> divideMessage (String text)

Added in API level 4

Divide a message text into several fragments, none bigger than the maximum SMS message size.

Parameters
text the original message. Must not be null.
Returns
  • an ArrayList of strings that, in order, comprise the original message
Throws
IllegalArgumentException if text is null

public void downloadMultimediaMessage (Context context, String locationUrl, Uri contentUri, Bundle configOverrides, PendingIntent downloadedIntent)

Added in API level 21

Download an MMS message from carrier by a given location URL

Parameters
context application context
locationUrl the location URL of the MMS message to be downloaded, usually obtained from the MMS WAP push notification
contentUri the content uri to which the downloaded pdu will be written
configOverrides the carrier-specific messaging configuration values to override for downloading the message.
downloadedIntent if not NULL this PendingIntent is broadcast when the message is downloaded, or the download is failed
Throws
IllegalArgumentException if locationUrl or contentUri is empty

public Bundle getCarrierConfigValues ()

Added in API level 21

Get carrier-dependent configuration values.

Returns
  • bundle key/values pairs of configuration values

public static SmsManager getDefault ()

Added in API level 4

Get the SmsManager associated with the default subscription id. The instance will always be associated with the default subscription id, even if the default subscription id is changed.

Returns
  • the SmsManager associated with the default subscription id

public static int getDefaultSmsSubscriptionId ()

Get default sms subscription id

Returns
  • the default SMS subscription id

public static SmsManager getSmsManagerForSubscriptionId (int subId)

Get the the instance of the SmsManager associated with a particular subscription id

Parameters
subId an SMS subscription id, typically accessed using SubscriptionManager
Returns
  • the instance of the SmsManager associated with subId

public int getSubscriptionId ()

Get the associated subscription id. If the instance was returned by getDefault(), then this method may return different values at different points in time (if the user changes the default subscription id). It will return < 0 if the default subscription id cannot be determined. Additionally, to support legacy applications that are not multi-SIM aware, if the following are true: - We are using a multi-SIM device - A default SMS SIM has not been selected - At least one SIM subscription is available then ask the user to set the default SMS SIM.

Returns
  • associated subscription id

public void injectSmsPdu (byte[] pdu, String format, PendingIntent receivedIntent)

Inject an SMS PDU into the android application framework. The caller should have carrier privileges.

Parameters
pdu is the byte array of pdu to be injected into android application framework
format is the format of SMS pdu (3gpp or 3gpp2)
receivedIntent if not NULL this PendingIntent is broadcast when the message is successfully received by the android application framework, or failed. This intent is broadcasted at the same time an SMS received from radio is acknowledged back. The result code will be RESULT_SMS_HANDLED for success, or RESULT_SMS_GENERIC_ERROR for error.
Throws
IllegalArgumentException if format is not one of 3gpp and 3gpp2.

public void sendDataMessage (String destinationAddress, String scAddress, short destinationPort, byte[] data, PendingIntent sentIntent, PendingIntent deliveryIntent)

Added in API level 4

Send a data based SMS to a specific application port.

Note: Using this method requires that your app has the SEND_SMS permission.

Parameters
destinationAddress the address to send the message to
scAddress is the service center address or null to use the current default SMSC
destinationPort the port to deliver the message to
data the body of the message to send
sentIntent if not NULL this PendingIntent is broadcast when the message is successfully sent, or failed. The result code will be Activity.RESULT_OK for success, or one of these errors:
RESULT_ERROR_GENERIC_FAILURE
RESULT_ERROR_RADIO_OFF
RESULT_ERROR_NULL_PDU
For RESULT_ERROR_GENERIC_FAILURE the sentIntent may include the extra "errorCode" containing a radio technology specific value, generally only useful for troubleshooting.
The per-application based SMS control checks sentIntent. If sentIntent is NULL the caller will be checked against all unknown applications, which cause smaller number of SMS to be sent in checking period.
deliveryIntent if not NULL this PendingIntent is broadcast when the message is delivered to the recipient. The raw pdu of the status report is in the extended data ("pdu").
Throws
IllegalArgumentException if destinationAddress or data are empty

public void sendMultimediaMessage (Context context, Uri contentUri, String locationUrl, Bundle configOverrides, PendingIntent sentIntent)

Added in API level 21

Send an MMS message

Parameters
context application context
contentUri the content Uri from which the message pdu will be read
locationUrl the optional location url where message should be sent to
configOverrides the carrier-specific messaging configuration values to override for sending the message.
sentIntent if not NULL this PendingIntent is broadcast when the message is successfully sent, or failed
Throws
IllegalArgumentException if contentUri is empty

public void sendMultipartTextMessage (String destinationAddress, String scAddress, ArrayList<String> parts, ArrayList<PendingIntent> sentIntents, ArrayList<PendingIntent> deliveryIntents)

Added in API level 4

Send a multi-part text based SMS. The callee should have already divided the message into correctly sized parts by calling divideMessage.

Note: Using this method requires that your app has the SEND_SMS permission.

Note: Beginning with Android 4.4 (API level 19), if and only if an app is not selected as the default SMS app, the system automatically writes messages sent using this method to the SMS Provider (the default SMS app is always responsible for writing its sent messages to the SMS Provider). For information about how to behave as the default SMS app, see Telephony.

Parameters
destinationAddress the address to send the message to
scAddress is the service center address or null to use the current default SMSC
parts an ArrayList of strings that, in order, comprise the original message
sentIntents if not null, an ArrayList of PendingIntents (one for each message part) that is broadcast when the corresponding message part has been sent. The result code will be Activity.RESULT_OK for success, or one of these errors:
RESULT_ERROR_GENERIC_FAILURE
RESULT_ERROR_RADIO_OFF
RESULT_ERROR_NULL_PDU
For RESULT_ERROR_GENERIC_FAILURE each sentIntent may include the extra "errorCode" containing a radio technology specific value, generally only useful for troubleshooting.
The per-application based SMS control checks sentIntent. If sentIntent is NULL the caller will be checked against all unknown applications, which cause smaller number of SMS to be sent in checking period.
deliveryIntents if not null, an ArrayList of PendingIntents (one for each message part) that is broadcast when the corresponding message part has been delivered to the recipient. The raw pdu of the status report is in the extended data ("pdu").
Throws
IllegalArgumentException if destinationAddress or data are empty

public void sendTextMessage (String destinationAddress, String scAddress, String text, PendingIntent sentIntent, PendingIntent deliveryIntent)

Added in API level 4

Send a text based SMS.

Note: Using this method requires that your app has the SEND_SMS permission.

Note: Beginning with Android 4.4 (API level 19), if and only if an app is not selected as the default SMS app, the system automatically writes messages sent using this method to the SMS Provider (the default SMS app is always responsible for writing its sent messages to the SMS Provider). For information about how to behave as the default SMS app, see Telephony.

Parameters
destinationAddress the address to send the message to
scAddress is the service center address or null to use the current default SMSC
text the body of the message to send
sentIntent if not NULL this PendingIntent is broadcast when the message is successfully sent, or failed. The result code will be Activity.RESULT_OK for success, or one of these errors:
RESULT_ERROR_GENERIC_FAILURE
RESULT_ERROR_RADIO_OFF
RESULT_ERROR_NULL_PDU
For RESULT_ERROR_GENERIC_FAILURE the sentIntent may include the extra "errorCode" containing a radio technology specific value, generally only useful for troubleshooting.
The per-application based SMS control checks sentIntent. If sentIntent is NULL the caller will be checked against all unknown applications, which cause smaller number of SMS to be sent in checking period.
deliveryIntent if not NULL this PendingIntent is broadcast when the message is delivered to the recipient. The raw pdu of the status report is in the extended data ("pdu").
Throws
IllegalArgumentException if destinationAddress or text are empty