1# @ohos.telephony.sms (SMS) 2 3The **sms** module provides basic SMS management functions. With the APIs provided by this module, you can create and send SMS messages, and obtain the ID of the default SIM card used to send and receive SMS messages, and check whether the current device can send and receive SMS messages. 4 5>**NOTE** 6> 7>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. 8 9## Modules to Import 10 11```ts 12import { sms } from '@kit.TelephonyKit'; 13``` 14 15## sms.createMessage 16 17createMessage\(pdu: Array<number>, specification: string, callback: AsyncCallback\<ShortMessage\>\): void 18 19Creates an SMS instance based on the protocol data unit (PDU) and specified SMS protocol. This API uses an asynchronous callback to return the result. 20 21**System capability**: SystemCapability.Telephony.SmsMms 22 23**Parameters** 24 25| Name | Type | Mandatory| Description | 26| ------------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 27| pdu | Array<number> | Yes | Protocol data unit, which is obtained from the received SMS message. | 28| specification | string | Yes | SMS protocol type. <br>- **3gpp**: GSM/UMTS/LTE SMS<br>- **3gpp2**: CDMA SMS| 29| callback | AsyncCallback<[ShortMessage](#shortmessage)> | Yes | Callback used to return the result. | 30 31**Error codes** 32 33For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 34 35| ID| Error Message | 36| -------- | -------------------------------------------- | 37| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 38| 8300001 | Invalid parameter value. | 39| 8300002 | Operation failed. Cannot connect to service. | 40| 8300003 | System internal error. | 41| 8300999 | Unknown error code. | 42 43**Example** 44 45```ts 46import { sms } from '@kit.TelephonyKit'; 47import { BusinessError } from '@kit.BasicServicesKit'; 48 49const specification: string = '3gpp'; 50// Display PDUs in array format. The type is number. 51const pdu: Array<number> = [0x01, 0x00, 0x05, 0x81, 0x01, 0x80, 0xF6, 0x00, 0x00, 0x05, 0xE8, 0x32, 0x9B, 0xFD, 0x06]; 52sms.createMessage(pdu, specification, (err: BusinessError, data: sms.ShortMessage) => { 53 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 54}); 55``` 56 57 58## sms.createMessage 59 60createMessage\(pdu: Array<number>, specification: string\): Promise\<ShortMessage\> 61 62Creates an SMS instance based on the PDU and specified SMS protocol. This API uses a promise to return the result. 63 64**System capability**: SystemCapability.Telephony.SmsMms 65 66**Parameters** 67 68| Name | Type | Mandatory| Description | 69| ------------- | ------------------- | ---- | ------------------------------------------------------------ | 70| pdu | Array<number> | Yes | Protocol data unit, which is obtained from the received SMS message. | 71| specification | string | Yes | SMS protocol type. <br>- **3gpp**: GSM/UMTS/LTE SMS<br>- **3gpp2**: CDMA SMS| 72 73**Return value** 74 75| Type | Description | 76| -------------------------------------------- | --------------------------------- | 77| Promise<[ShortMessage](#shortmessage)> | Promise used to return the result.| 78 79**Error codes** 80 81For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 82 83| ID| Error Message | 84| -------- | -------------------------------------------- | 85| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 86| 8300001 | Invalid parameter value. | 87| 8300002 | Operation failed. Cannot connect to service. | 88| 8300003 | System internal error. | 89| 8300999 | Unknown error code. | 90 91**Example** 92 93```ts 94import { sms } from '@kit.TelephonyKit'; 95import { BusinessError } from '@kit.BasicServicesKit'; 96 97const specification: string = '3gpp'; 98// Display PDUs in array format. The type is number. 99const pdu: Array<number> = [0x01, 0x00, 0x05, 0x81, 0x01, 0x80, 0xF6, 0x00, 0x00, 0x05, 0xE8, 0x32, 0x9B, 0xFD, 0x06]; 100sms.createMessage(pdu, specification).then((data: sms.ShortMessage) => { 101 console.log(`createMessage success, promise: data->${JSON.stringify(data)}`); 102}).catch((err: BusinessError) => { 103 console.error(`createMessage failed, promise: err->${JSON.stringify(err)}`); 104}); 105``` 106 107## sms.sendMessage<sup>(deprecated)</sup> 108 109sendMessage\(options: SendMessageOptions\): void 110 111Sends an SMS message. 112 113> **NOTE** 114> 115> This API is supported since API version 6 and deprecated since API version 10. You are advised to use [sendShortMessage](#smssendshortmessage10). 116 117**Required permissions**: ohos.permission.SEND_MESSAGES (available only for system applications) 118 119**System capability**: SystemCapability.Telephony.SmsMms 120 121**Parameters** 122 123| Name | Type | Mandatory| Description | 124| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 125| options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending SMS messages. For details, see [SendMessageOptions](#sendmessageoptions).| 126 127**Error codes** 128 129For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 130 131| ID| Error Message | 132| -------- | -------------------------------------------- | 133| 201 | Permission denied. | 134| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 135| 8300001 | Invalid parameter value. | 136| 8300002 | Operation failed. Cannot connect to service. | 137| 8300003 | System internal error. | 138| 8300999 | Unknown error code. | 139 140**Example** 141 142```ts 143import { sms } from '@kit.TelephonyKit'; 144import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 145 146let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 147 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 148}; 149let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 150 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 151}; 152let options: sms.SendMessageOptions = { 153 slotId: 0, 154 content: 'SMS message content'; 155 destinationHost: '+861xxxxxxxxxx', 156 serviceCenter: '+861xxxxxxxxxx', 157 destinationPort: 1000, 158 sendCallback: sendCallback, 159 deliveryCallback: deliveryCallback 160}; 161sms.sendMessage(options); 162``` 163 164## sms.sendShortMessage<sup>10+</sup> 165 166sendShortMessage\(options: SendMessageOptions, callback: AsyncCallback<void>\): void 167 168Sends an SMS message. This API uses an asynchronous callback to return the result. 169 170**Required permissions**: ohos.permission.SEND_MESSAGES (available only for system applications) 171 172**System capability**: SystemCapability.Telephony.SmsMms 173 174**Parameters** 175 176| Name | Type | Mandatory| Description | 177| -------- | --------------------------- | ---- | ---------------------------------------- | 178| options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending SMS messages. For details, see [SendMessageOptions](#sendmessageoptions).| 179| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 180 181**Error codes** 182 183For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 184 185| ID| Error Message | 186| -------- | -------------------------------------------- | 187| 201 | Permission denied. | 188| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 189| 8300001 | Invalid parameter value. | 190| 8300002 | Operation failed. Cannot connect to service. | 191| 8300003 | System internal error. | 192| 8300999 | Unknown error code. | 193 194**Example** 195 196```ts 197import { sms } from '@kit.TelephonyKit'; 198import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 199 200let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 201 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 202}; 203let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 204 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 205}; 206let options: sms.SendMessageOptions = { 207 slotId: 0, 208 content: 'SMS message content'; 209 destinationHost: '+861xxxxxxxxxx', 210 serviceCenter: '+861xxxxxxxxxx', 211 destinationPort: 1000, 212 sendCallback: sendCallback, 213 deliveryCallback: deliveryCallback 214}; 215sms.sendShortMessage(options, (err: BusinessError) => { 216 console.log(`callback: err->${JSON.stringify(err)}`); 217}); 218``` 219 220## sms.sendShortMessage<sup>10+</sup> 221 222sendShortMessage\(options: SendMessageOptions\): Promise<void> 223 224Sends an SMS message. This API uses a promise to return the result. 225 226**Required permissions**: ohos.permission.SEND_MESSAGES (available only for system applications) 227 228**System capability**: SystemCapability.Telephony.SmsMms 229 230**Parameters** 231 232| Name | Type | Mandatory| Description | 233| -------- | --------------------------- | ---- | ---------------------------------------- | 234| options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending SMS messages. For details, see [SendMessageOptions](#sendmessageoptions).| 235 236**Return value** 237 238| Type | Description | 239| --------------- | ------------------------------------------------------------ | 240| Promise<void> | Promise used to return the result.| 241 242**Error codes** 243 244For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 245 246| ID| Error Message | 247| -------- | -------------------------------------------- | 248| 201 | Permission denied. | 249| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 250| 8300001 | Invalid parameter value. | 251| 8300002 | Operation failed. Cannot connect to service. | 252| 8300003 | System internal error. | 253| 8300999 | Unknown error code. | 254 255**Example** 256 257```ts 258import { sms } from '@kit.TelephonyKit'; 259import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 260 261let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 262 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 263}; 264let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 265 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 266}; 267let options: sms.SendMessageOptions = { 268 slotId: 0, 269 content: 'SMS message content'; 270 destinationHost: '+861xxxxxxxxxx', 271 serviceCenter: '+861xxxxxxxxxx', 272 destinationPort: 1000, 273 sendCallback: sendCallback, 274 deliveryCallback: deliveryCallback 275}; 276let promise = sms.sendShortMessage(options); 277promise.then(() => { 278 console.log(`sendShortMessage success`); 279}).catch((err: BusinessError) => { 280 console.error(`sendShortMessage failed, promise: err->${JSON.stringify(err)}`); 281}); 282 283``` 284 285 286## sms.getDefaultSmsSlotId<sup>7+</sup> 287 288getDefaultSmsSlotId\(callback: AsyncCallback<number>\): void 289 290Obtains the default slot ID of the SIM card used to send SMS messages. This API uses an asynchronous callback to return the result. 291 292**System capability**: SystemCapability.Telephony.SmsMms 293 294**Parameters** 295 296| Name | Type | Mandatory| Description | 297| -------- | --------------------------- | ---- | ---------------------------------------- | 298| callback | AsyncCallback<number> | Yes | Callback used to return the result.<br>- **0**: card slot 1<br>- **1**: card slot 2| 299 300**Example** 301 302```ts 303import { sms } from '@kit.TelephonyKit'; 304import { BusinessError } from '@kit.BasicServicesKit'; 305 306sms.getDefaultSmsSlotId((err: BusinessError, data: number) => { 307 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 308}); 309``` 310 311 312## sms.getDefaultSmsSlotId<sup>7+</sup> 313 314getDefaultSmsSlotId\(\): Promise<number> 315 316Obtains the default slot ID of the SIM card used to send SMS messages. This API uses a promise to return the result. 317 318**System capability**: SystemCapability.Telephony.SmsMms 319 320**Return value** 321 322| Type | Description | 323| --------------- | ------------------------------------------------------------ | 324| Promise<number> | Promise used to return the result.<br>- **0**: card slot 1<br>- **1**: card slot 2| 325 326**Example** 327 328```ts 329import { sms } from '@kit.TelephonyKit'; 330import { BusinessError } from '@kit.BasicServicesKit'; 331 332sms.getDefaultSmsSlotId().then((data: number) => { 333 console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); 334}).catch((err: BusinessError) => { 335 console.error(`getDefaultSmsSlotId failed, promise: err->${JSON.stringify(err)}`); 336}); 337``` 338 339## sms.hasSmsCapability<sup>7+</sup> 340 341hasSmsCapability\(\): boolean 342 343Checks whether the current device can send and receive SMS messages. This API works in synchronous mode. 344 345**System capability**: SystemCapability.Telephony.SmsMms 346 347**Return value** 348 349| Type | Description | 350| ------- | ------------------------------------------------------------ | 351| boolean | - **true**: The device can send and receive SMS messages.<br>- **false**: The device cannot send or receive SMS messages.| 352 353```ts 354import { sms } from '@kit.TelephonyKit'; 355 356let result = sms.hasSmsCapability(); 357console.log(`hasSmsCapability: ${JSON.stringify(result)}`); 358``` 359 360## sms.getDefaultSmsSimId<sup>10+</sup> 361 362getDefaultSmsSimId\(callback: AsyncCallback<number>\): void 363 364Obtains the default ID of the SIM card used to send SMS messages. This API uses an asynchronous callback to return the result. 365 366**System capability**: SystemCapability.Telephony.SmsMms 367 368**Parameters** 369 370| Name | Type | Mandatory| Description | 371| -------- | --------------------------- | ---- | ---------------------------------------- | 372| callback | AsyncCallback<number> | Yes | Callback used to return the result.<br>The return value is bound to the SIM card and increases from 1.<br>The return value is **-1** if no SIM card is detected.| 373 374**Error codes** 375 376For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 377 378| ID| Error Message | 379| -------- | -------------------------------------------- | 380| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 381| 8300001 | Invalid parameter value. | 382| 8300002 | Operation failed. Cannot connect to service. | 383| 8300003 | System internal error. | 384| 8300004 | Do not have sim card. | 385| 8300999 | Unknown error code. | 386| 8301001 | SIM card is not activated. | 387 388**Example** 389 390```ts 391import { sms } from '@kit.TelephonyKit'; 392import { BusinessError } from '@kit.BasicServicesKit'; 393 394sms.getDefaultSmsSimId((err: BusinessError, data: number) => { 395 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 396}); 397``` 398 399 400## sms.getDefaultSmsSimId<sup>10+</sup> 401 402getDefaultSmsSimId\(\): Promise<number> 403 404Obtains the default ID of the SIM card used to send SMS messages. This API uses a promise to return the result. 405 406**System capability**: SystemCapability.Telephony.SmsMms 407 408**Return value** 409 410| Type | Description | 411| --------------- | ------------------------------------------------------------ | 412| Promise<number> | Promise used to return the result.<br>The return value is bound to the SIM card and increases from 1.<br>The return value is **-1** if no SIM card is detected.| 413 414**Error codes** 415 416For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 417 418| ID| Error Message | 419| -------- | -------------------------------------------- | 420| 8300001 | Invalid parameter value. | 421| 8300002 | Operation failed. Cannot connect to service. | 422| 8300003 | System internal error. | 423| 8300004 | Do not have sim card. | 424| 8300999 | Unknown error code. | 425| 8301001 | SIM card is not activated. | 426 427**Example** 428 429```ts 430import { sms } from '@kit.TelephonyKit'; 431import { BusinessError } from '@kit.BasicServicesKit'; 432 433let promise = sms.getDefaultSmsSimId(); 434promise.then((data: number) => { 435 console.log(`getDefaultSmsSimId success, promise: data->${JSON.stringify(data)}`); 436}).catch((err: BusinessError) => { 437 console.error(`getDefaultSmsSimId failed, promise: err->${JSON.stringify(err)}`); 438}); 439``` 440 441 442## ShortMessage 443 444Defines an SMS message instance. 445 446**System capability**: SystemCapability.Telephony.SmsMms 447 448| Name | Type | Mandatory| Description | 449| ------------------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 450| hasReplyPath | boolean | Yes | Whether the received SMS contains **TP-Reply-Path**. The default value is **false**.<br>TP-Reply-Path: The device returns a response based on the SMSC that sends the SMS message. | 451| isReplaceMessage | boolean | Yes | Whether the received SMS message is a **replace short message**. The default value is **false**.<br>For details, see [3GPP TS 23.040 9.2.3.9](https://www.3gpp.org/ftp/specs/archive/23_series/23.040).| 452| isSmsStatusReportMessage | boolean | Yes | Whether the received SMS message is an SMS delivery report. The default value is **false**.<br>SMS delivery report: a message sent from the SMSC to show the current status of the SMS message you delivered.| 453| messageClass | [ShortMessageClass](#shortmessageclass) | Yes | Enumerates SMS message types. | 454| pdu | Array<number> | Yes | PDU in the SMS message. | 455| protocolId | number | Yes | Protocol identifier used for delivering the SMS message. | 456| scAddress | string | Yes | SMSC address. | 457| scTimestamp | number | Yes | SMSC timestamp. | 458| status | number | Yes | SMS message status sent by the SMSC in the **SMS-STATUS-REPORT** message.| 459| visibleMessageBody | string | Yes | SMS message body. | 460| visibleRawAddress | string | Yes | Sender address. | 461 462 463## ShortMessageClass 464 465Enumerates SMS message types. 466 467**System capability**: SystemCapability.Telephony.SmsMms 468 469| Name | Value | Description | 470| ---------------- | ---- | ---------------------------------------- | 471| UNKNOWN | 0 | Unknown type. | 472| INSTANT_MESSAGE | 1 | Instant message, which is displayed immediately after being received. | 473| OPTIONAL_MESSAGE | 2 | Message stored in the device or SIM card. | 474| SIM_MESSAGE | 3 | Message containing SIM card information, which is to be stored in the SIM card.| 475| FORWARD_MESSAGE | 4 | Message to be forwarded to another device. | 476 477 478## SendMessageOptions 479 480Provides the options (including callbacks) for sending SMS messages. For example, you can specify the SMS message type by the optional parameter **content**. 481 482**System capability**: SystemCapability.Telephony.SmsMms 483 484| Name | Type | Mandatory| Description | 485| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 486| slotId | number | Yes | Slot ID of the SIM card used for sending SMS messages. <br>- **0**: card slot 1<br>- **1**: card slot 2 | 487| destinationHost | string | Yes | Destination address of the SMS message. | 488| 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.| 489| serviceCenter | string | No | SMSC address. By default, the SMSC address in the SIM card is used. | 490| destinationPort | number | No | Destination port of the SMS message. This field is mandatory only for a data message. Otherwise, it is optional. | 491| sendCallback | AsyncCallback<[ISendShortMessageCallback](#isendshortmessagecallback)> | No | Callback used to return the SMS message sending result. For details, see [ISendShortMessageCallback](#isendshortmessagecallback). This parameter is mandatory for sending an SMS message.| 492| deliveryCallback | AsyncCallback<[IDeliveryShortMessageCallback](#ideliveryshortmessagecallback)> | No | Callback used to return the SMS message delivery report. For details, see [IDeliveryShortMessageCallback](#ideliveryshortmessagecallback). This parameter is mandatory for sending an SMS message.| 493 494 495 496## ISendShortMessageCallback 497 498Provides 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. 499 500**System capability**: SystemCapability.Telephony.SmsMms 501 502| Name | Type | Mandatory| Description | 503| ---------- | ------------------------------- | ---- | ----------------------------------------------------------------------------------------- | 504| isLastPart | boolean | Yes | 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**.| 505| result | [SendSmsResult](#sendsmsresult) | Yes | SMS message sending result. | 506| url | string | Yes | URI for storing the sent SMS message. | 507 508 509## IDeliveryShortMessageCallback 510 511Provides the callback for the SMS message delivery report. 512 513**System capability**: SystemCapability.Telephony.SmsMms 514 515| Name| Type | Mandatory| Description | 516| ---- | ------------------- | ---- | -------------- | 517| pdu | Array<number> | Yes | SMS message delivery report.| 518 519 520## SendSmsResult 521 522Enumerates SMS message sending results. 523 524**System capability**: SystemCapability.Telephony.SmsMms 525 526| Name | Value | Description | 527| ------------------------------------ | ---- | ------------------------------------------------------ | 528| SEND_SMS_SUCCESS | 0 | The SMS message is sent successfully. | 529| SEND_SMS_FAILURE_UNKNOWN | 1 | Failed to send the SMS message due to an unknown reason. | 530| SEND_SMS_FAILURE_RADIO_OFF | 2 | Failed to send the SMS message because the modem is shut down. | 531| 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.| 532