1# SMS 2 3> **NOTE**<br> 4> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 5 6## Modules to Import 7 8``` 9import sms from '@ohos.telephony.sms'; 10``` 11 12## sms.createMessage 13 14createMessage\(pdu: Array\<number\>, specification: string, callback: AsyncCallback<ShortMessage\>\): void 15 16Creates an SMS message instance based on the protocol data unit (PDU) and the specified SMS protocol. This API uses an asynchronous callback to return the result. 17 18**System capability**: SystemCapability.Telephony.SmsMms 19 20**Parameters** 21 22| Name | Type | Mandatory| Description | 23| ------------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 24| pdu | Array<number> | Yes | PDU, which is obtained from the received SMS message. | 25| specification | string | Yes | SMS protocol type. <br>- **3gpp**: GSM/UMTS/LTE SMS<br>- **3gpp2**: CDMA SMS| 26| callback | AsyncCallback<[ShortMessage](#shortmessage)> | Yes | Callback used to return the result. | 27 28**Example** 29 30``` 31const specification = '3gpp'; 32// Display PDUs using numbers in an array, for example, [0x08, 0x91, ...]. 33const pdu = [0x08, 0x91]; 34sms.createMessage(pdu, specification, (err, data) => { 35 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 36}); 37``` 38 39 40## sms.createMessage 41 42createMessage\(pdu: Array\<number\>, specification: string\): Promise<ShortMessage\> 43 44Creates an SMS message instance based on the PDU and the specified SMS protocol. This API uses a promise to return the result. 45 46**System capability**: SystemCapability.Telephony.SmsMms 47 48**Parameters** 49 50| Name | Type | Mandatory| Description | 51| ------------- | ------------------- | ---- | ------------------------------------------------------------ | 52| pdu | Array<number> | Yes | PDU, which is obtained from the received SMS message. | 53| specification | string | Yes | SMS protocol type. <br>- **3gpp**: GSM/UMTS/LTE SMS<br>- **3gpp2**: CDMA SMS| 54 55**Return Value** 56 57| Type | Description | 58| -------------------------------------------- | --------------------------------- | 59| Promise<[ShortMessage](#shortmessage)> | Promise used to return the result.| 60 61**Example** 62 63``` 64const specification = '3gpp'; 65// Display PDUs using numbers in an array, for example, [0x08, 0x91, ...]. 66const pdu = [0x08, 0x91]; 67let promise = sms.createMessage(pdu, specification); 68promise.then(data => { 69 console.log(`createMessage success, promise: data->${JSON.stringify(data)}`); 70}).catch(err => { 71 console.error(`createMessage fail, promise: err->${JSON.stringify(err)}`); 72}); 73``` 74 75## sms.sendMessage 76 77sendMessage(options: SendMessageOptions): void 78 79Sends an SMS message. 80 81**Required permission**: ohos.permission.SEND_MESSAGES 82 83**System capability**: SystemCapability.Telephony.SmsMms 84 85**Parameters** 86 87| Name | Type | Mandatory| Description | 88| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 89| options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending an SMS message. For details, see [SendMessageOptions](#sendmessageoptions).| 90 91**Example** 92 93``` 94let sendCallback = function (err, data) { 95 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 96} 97let deliveryCallback = function (err, data) { 98 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 99} 100let slotId = 0; 101let content ='SMS message content'; 102let destinationHost = '+861xxxxxxxxxx'; 103let serviceCenter = '+861xxxxxxxxxx'; 104let destinationPort = 1000; 105let options = {slotId, content, destinationHost, serviceCenter, destinationPort, sendCallback, deliveryCallback}; 106sms.sendMessage(options); 107``` 108 109 110## sms.getDefaultSmsSlotId<sup>7+</sup> 111 112getDefaultSmsSlotId\(callback: AsyncCallback\<number\>\): void 113 114Obtains the default slot of the SIM card used to send SMS messages. This API uses an asynchronous callback to return the result. 115 116**System capability**: SystemCapability.Telephony.SmsMms 117 118**Parameters** 119 120| Name | Type | Mandatory| Description | 121| -------- | --------------------------- | ---- | ---------------------------------------- | 122| callback | AsyncCallback<number> | Yes | Callback used to return the result.<br>- **0**: card slot 1<br>- **1**: card slot 2| 123 124**Example** 125 126``` 127sms.getDefaultSmsSlotId((err, data) => { 128 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 129}); 130``` 131 132 133## sms.getDefaultSmsSlotId<sup>7+</sup> 134 135getDefaultSmsSlotId\(\): Promise\<number\> 136 137Obtains the default slot of the SIM card used to send SMS messages. This API uses a promise to return the result. 138 139**System capability**: SystemCapability.Telephony.SmsMms 140 141**Return Value** 142 143| Type | Description | 144| --------------- | ------------------------------------------------------------ | 145| Promise\<number> | Promise used to return the result.<br>- **0**: card slot 1<br>- **1**: card slot 2| 146 147**Example** 148 149``` 150let promise = sms.getDefaultSmsSlotId(); 151promise.then(data => { 152 console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); 153}).catch(err => { 154 console.error(`getDefaultSmsSlotId fail, promise: err->${JSON.stringify(err)}`); 155}); 156``` 157 158 159## sms.setSmscAddr<sup>7+</sup> 160 161setSmscAddr\(slotId: number, smscAddr: string, callback: AsyncCallback<void\>\): void 162 163Sets the short message service center (SMSC) address. This API uses an asynchronous callback to return the result. 164 165**Required permission**: ohos.permission.SET_TELEPHONY_STATE (a system permission) 166 167**System capability**: SystemCapability.Telephony.SmsMms 168 169This is a system API and cannot be called by third-party applications. 170 171**Parameters** 172 173| Name | Type | Mandatory| Description | 174| -------- | ------------------------- | ---- | ----------------------------------------- | 175| slotId | number | Yes | SIM card slot ID. <br>- **0**: card slot 1<br>- **1**: card slot 2| 176| smscAddr | string | Yes | SMSC address. | 177| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 178 179**Example** 180 181``` 182let slotId = 0; 183let smscAddr = '+861xxxxxxxxxx'; 184sms.setSmscAddr(slotId, smscAddr, (err,data) => { 185 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 186}); 187``` 188 189 190## sms.setSmscAddr<sup>7+</sup> 191 192setSmscAddr\(slotId: number, smscAddr: string\): Promise<void\> 193 194Sets the SMSC address. This API uses a promise to return the result. 195 196**Required permission**: ohos.permission.SET_TELEPHONY_STATE (a system permission) 197 198**System capability**: SystemCapability.Telephony.SmsMms 199 200This is a system API and cannot be called by third-party applications. 201 202**Parameters** 203 204| Name | Type | Mandatory| Description | 205| -------- | ------ | ---- | ----------------------------------------- | 206| slotId | number | Yes | SIM card slot ID. <br>- **0**: card slot 1<br>- **1**: card slot 2| 207| smscAddr | string | Yes | SMSC address. | 208 209**Return Value** 210 211| Type | Description | 212| ------------------- | ------------------------------- | 213| Promise<void> | Promise used to return the result.| 214 215**Example** 216 217``` 218let slotId = 0; 219let smscAddr = '+861xxxxxxxxxx'; 220let promise = sms.setSmscAddr(slotId, smscAddr); 221promise.then(data => { 222 console.log(`setSmscAddr success, promise: data->${JSON.stringify(data)}`); 223}).catch(err => { 224 console.error(`setSmscAddr fail, promise: err->${JSON.stringify(err)}`); 225}); 226``` 227 228 229## sms.getSmscAddr<sup>7+</sup> 230 231getSmscAddr\(slotId: number, callback: AsyncCallback<string\>\): void 232 233Obtains the SMSC address. This API uses an asynchronous callback to return the result. 234 235**Required permission**: ohos.permission.GET_TELEPHONY_STATE (a system permission) 236 237**System capability**: SystemCapability.Telephony.SmsMms 238 239This is a system API and cannot be called by third-party applications. 240 241**Parameters** 242 243| Name | Type | Mandatory| Description | 244| -------- | --------------------------- | ---- | ----------------------------------------- | 245| slotId | number | Yes | SIM card slot ID. <br>- **0**: card slot 1<br>- **1**: card slot 2| 246| callback | AsyncCallback<string> | Yes | Callback used to return the result. | 247 248**Example** 249 250``` 251let slotId = 0; 252sms.getSmscAddr(slotId, (err, data) => { 253 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 254}); 255``` 256 257 258## sms.getSmscAddr<sup>7+</sup> 259 260getSmscAddr\(slotId: number\): Promise<string\> 261 262Obtains the SMSC address. This API uses a promise to return the result. 263 264**Required permission**: ohos.permission.GET_TELEPHONY_STATE (a system permission) 265 266**System capability**: SystemCapability.Telephony.SmsMms 267 268This is a system API and cannot be called by third-party applications. 269 270**Parameters** 271 272| Name| Type | Mandatory| Description | 273| ------ | ------ | ---- | ----------------------------------------- | 274| slotId | number | Yes | SIM card slot ID. <br>- **0**: card slot 1<br>- **1**: card slot 2| 275 276**Return Value** 277 278| Type | Description | 279| --------------------- | --------------------------------------------- | 280| Promise<string> | Promise used to return the result.| 281 282**Example** 283 284``` 285let slotId = 0; 286let promise = sms.getSmscAddr(slotId); 287promise.then(data => { 288 console.log(`getSmscAddr success, promise: data->${JSON.stringify(data)}`); 289}).catch(err => { 290 console.error(`getSmscAddr fail, promise: err->${JSON.stringify(err)}`); 291}); 292``` 293 294## sms.hasSmsCapability<sup>7+</sup> 295 296hasSmsCapability(): boolean 297 298Checks whether the current device can send and receive SMS messages. This API works in synchronous mode. 299 300**System capability**: SystemCapability.Telephony.SmsMms 301 302**Return Value** 303 304| Type | Description | 305| ------- | ------------------------------------------------------------ | 306| boolean | - **true**: The device can send and receive SMS messages.<br>- **false**: The device cannot send or receive SMS messages.| 307 308``` 309let result = sms.hasSmsCapability(); 310console.log(`hasSmsCapability: ${JSON.stringify(result)}`); 311``` 312 313## ShortMessage 314 315Defines an SMS message instance. 316 317**System capability**: SystemCapability.Telephony.SmsMms 318 319| Name | Type | Description | 320| ------------------------ | --------------------------------------- | ------------------------------------------------------------ | 321| hasReplyPath | boolean | Whether the received SMS contains **TP-Reply-Path**. The default value is **false**.<br>**TP-Reply-Path**: the path in which the mobile phone can reply to the SMS message through the originating SMSC.| 322| isReplaceMessage | boolean | Whether the received SMS message is a **replace short message**. The default value is **false**.<br>For details, see section 9.2.3.9 in **3GPP TS 23.040**.| 323| isSmsStatusReportMessage | boolean | Whether the received SMS message is an SMS delivery status report. The default value is **false**.<br>**SMS-Status-Report**: a message sent from the SMSC to the mobile station to show the SMS message delivery status.| 324| messageClass | [ShortMessageClass](#shortmessageclass) | SMS message type. | 325| pdu | Array<number> | PDU in the SMS message. | 326| protocolId | number | ID of the protocol used for sending SMS messages. | 327| scAddress | string | Address of the short message service center (SMSC). | 328| scTimestamp | number | SMSC timestamp. | 329| status | number | SMS message status sent by the SMSC in the **SMS-STATUS-REPORT** message.| 330| visibleMessageBody | string | SMS message body. | 331| visibleRawAddress | string | Sender address. | 332 333 334## ShortMessageClass 335 336SMS message type. 337 338**System capability**: SystemCapability.Telephony.SmsMms 339 340| Name | Value | Description | 341| ---------------- | ---- | ---------------------------------------- | 342| UNKNOWN | 0 | Unknown type. | 343| INSTANT_MESSAGE | 1 | Instant message, which is displayed immediately after being received. | 344| OPTIONAL_MESSAGE | 2 | Message stored in the device or SIM card. | 345| SIM_MESSAGE | 3 | Message containing SIM card information, which is to be stored in the SIM card.| 346| FORWARD_MESSAGE | 4 | Message to be forwarded to another device. | 347 348 349## SendMessageOptions 350 351Provides the options (including callbacks) for sending an SMS message. For example, you can specify the SMS message type by the optional parameter **content**. 352 353**System capability**: SystemCapability.Telephony.SmsMms 354 355| Name | Type | Mandatory| Description | 356| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 357| slotId | number | Yes | Slot ID of the SIM card used for sending SMS messages. <br>- **0**: card slot 1<br>- **1**: card slot 2 | 358| destinationHost | string | Yes | Destination address of the SMS message. | 359| content | string \| Array<number> | Yes | SMS message type. If the content is composed of character strings, the SMS message is a text message. If the content is composed of byte arrays, the SMS message is a data message.| 360| serviceCenter | string | No | SMSC address. By default, the SMSC address in the SIM card is used. | 361| destinationPort | number | No | Destination port of the SMS message. This field is mandatory only for a data message. Otherwise, it is optional. | 362| sendCallback | AsyncCallback<[ISendShortMessageCallback](#isendshortmessagecallback)> | No | Callback used to return the SMS message sending result. For details, see [ISendShortMessageCallback](#isendshortmessagecallback).| 363| deliveryCallback | AsyncCallback<[IDeliveryShortMessageCallback](#ideliveryshortmessagecallback)> | No | Callback used to return the SMS message delivery report. For details, see [IDeliveryShortMessageCallback](#ideliveryshortmessagecallback).| 364 365 366## ISendShortMessageCallback 367 368Provides the callback for the SMS message sending result. It consists of three parts: SMS message sending result, URI for storing the sent SMS message, and whether the SMS message is the last part of a long SMS message. 369 370**System capability**: SystemCapability.Telephony.SmsMms 371 372| Name | Type | Mandatory| Description | 373| ---------- | ------------------------------- | ---- | ------------------------------------------------------------ | 374| isLastPart | boolean | No | Whether this SMS message is the last part of a long SMS message. The value **true** indicates that this SMS message is the last part of a long SMS message, and value **false** indicates the opposite. The default value is **false**.| 375| result | [SendSmsResult](#sendsmsresult) | Yes | SMS message sending result. | 376| url | string | Yes | URI for storing sent SMS messages. | 377 378 379## IDeliveryShortMessageCallback 380 381Provides the callback for the SMS message sending result. Return the SMS delivery report. 382 383**System capability**: SystemCapability.Telephony.SmsMms 384 385| Name| Type | Mandatory| Description | 386| ------ | ------------------- | ---- | -------------- | 387| pdu | Array<number> | Yes | SMS message delivery report.| 388 389 390## SendSmsResult 391 392SMS message sending result. 393 394**System capability**: SystemCapability.Telephony.SmsMms 395 396| Name | Value | Description | 397| ------------------------------------ | ---- | ------------------------------------------------------ | 398| SEND_SMS_SUCCESS | 0 | SMS message sent successfully. | 399| SEND_SMS_FAILURE_UNKNOWN | 1 | Failed to send the SMS message due to unknown reasons. | 400| SEND_SMS_FAILURE_RADIO_OFF | 2 | Failed to send the SMS message because the modem is shut down. | 401| SEND_SMS_FAILURE_SERVICE_UNAVAILABLE | 3 | Failed to send the SMS message because the network is unavailable or SMS message sending or receiving is not supported.| 402