1# @ohos.telephony.sms (SMS) 2 3The **sms** module provides basic SMS management functions. You can create and send SMS messages, and obtain and set the default SIM card for sending and receiving SMS messages. Besides, you can obtain and set the SMSC address, 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 '@ohos.telephony.sms'; 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. | 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 '@ohos.telephony.sms'; 47import { BusinessError } from '@ohos.base'; 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. | 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 '@ohos.telephony.sms'; 95import { BusinessError } from '@ohos.base'; 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 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. | 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 '@ohos.telephony.sms'; 144import { AsyncCallback } from '@ohos.base'; 145import { BusinessError } from '@ohos.base'; 146 147let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 148 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 149}; 150let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 151 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 152}; 153let options: sms.SendMessageOptions = { 154 slotId: 0, 155 content: 'SMS message content'; 156 destinationHost: '+861xxxxxxxxxx', 157 serviceCenter: '+861xxxxxxxxxx', 158 destinationPort: 1000, 159 sendCallback: sendCallback, 160 deliveryCallback: deliveryCallback 161}; 162sms.sendMessage(options); 163``` 164 165## sms.sendShortMessage<sup>10+</sup> 166 167sendShortMessage\(options: SendMessageOptions, callback: AsyncCallback<void>\): void 168 169Sends an SMS message. This API uses an asynchronous callback to return the result. 170 171**Required permissions**: ohos.permission.SEND_MESSAGES 172 173**System capability**: SystemCapability.Telephony.SmsMms 174 175**Parameters** 176 177| Name | Type | Mandatory| Description | 178| -------- | --------------------------- | ---- | ---------------------------------------- | 179| options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending SMS messages. For details, see [SendMessageOptions](#sendmessageoptions).| 180| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 181 182**Error codes** 183 184For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 185 186| ID| Error Message | 187| -------- | -------------------------------------------- | 188| 201 | Permission denied. | 189| 401 | Parameter error. | 190| 8300001 | Invalid parameter value. | 191| 8300002 | Operation failed. Cannot connect to service. | 192| 8300003 | System internal error. | 193| 8300999 | Unknown error code. | 194 195**Example** 196 197```ts 198import sms from '@ohos.telephony.sms'; 199import { AsyncCallback } from '@ohos.base'; 200import { BusinessError } from '@ohos.base'; 201 202let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 203 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 204}; 205let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 206 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 207}; 208let options: sms.SendMessageOptions = { 209 slotId: 0, 210 content: 'SMS message content'; 211 destinationHost: '+861xxxxxxxxxx', 212 serviceCenter: '+861xxxxxxxxxx', 213 destinationPort: 1000, 214 sendCallback: sendCallback, 215 deliveryCallback: deliveryCallback 216}; 217sms.sendShortMessage(options, (err: BusinessError) => { 218 console.log(`callback: err->${JSON.stringify(err)}`); 219}); 220``` 221 222## sms.sendShortMessage<sup>10+</sup> 223 224sendShortMessage\(options: SendMessageOptions\): Promise<void> 225 226Sends an SMS message. This API uses a promise to return the result. 227 228**Required permissions**: ohos.permission.SEND_MESSAGES 229 230**System capability**: SystemCapability.Telephony.SmsMms 231 232**Parameters** 233 234| Name | Type | Mandatory| Description | 235| -------- | --------------------------- | ---- | ---------------------------------------- | 236| options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending SMS messages. For details, see [SendMessageOptions](#sendmessageoptions).| 237 238**Return value** 239 240| Type | Description | 241| --------------- | ------------------------------------------------------------ | 242| Promise<void> | Promise used to return the result.| 243 244**Error codes** 245 246For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 247 248| ID| Error Message | 249| -------- | -------------------------------------------- | 250| 201 | Permission denied. | 251| 401 | Parameter error. | 252| 8300001 | Invalid parameter value. | 253| 8300002 | Operation failed. Cannot connect to service. | 254| 8300003 | System internal error. | 255| 8300999 | Unknown error code. | 256 257**Example** 258 259```ts 260import sms from '@ohos.telephony.sms'; 261import { AsyncCallback } from '@ohos.base'; 262import { BusinessError } from '@ohos.base'; 263 264let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 265 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 266}; 267let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 268 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 269}; 270let options: sms.SendMessageOptions = { 271 slotId: 0, 272 content: 'SMS message content'; 273 destinationHost: '+861xxxxxxxxxx', 274 serviceCenter: '+861xxxxxxxxxx', 275 destinationPort: 1000, 276 sendCallback: sendCallback, 277 deliveryCallback: deliveryCallback 278}; 279let promise = sms.sendShortMessage(options); 280promise.then(() => { 281 console.log(`sendShortMessage success`); 282}).catch((err: BusinessError) => { 283 console.error(`sendShortMessage failed, promise: err->${JSON.stringify(err)}`); 284}); 285 286``` 287 288 289## sms.getDefaultSmsSlotId<sup>7+</sup> 290 291getDefaultSmsSlotId\(callback: AsyncCallback<number>\): void 292 293Obtains the default slot ID of the SIM card used to send SMS messages. This API uses an asynchronous callback to return the result. 294 295**System capability**: SystemCapability.Telephony.SmsMms 296 297**Parameters** 298 299| Name | Type | Mandatory| Description | 300| -------- | --------------------------- | ---- | ---------------------------------------- | 301| callback | AsyncCallback<number> | Yes | Callback used to return the result.<br>- **0**: card slot 1<br>- **1**: card slot 2| 302 303**Example** 304 305```ts 306import sms from '@ohos.telephony.sms'; 307import { BusinessError } from '@ohos.base'; 308 309sms.getDefaultSmsSlotId((err: BusinessError, data: number) => { 310 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 311}); 312``` 313 314 315## sms.getDefaultSmsSlotId<sup>7+</sup> 316 317getDefaultSmsSlotId\(\): Promise<number> 318 319Obtains the default slot ID of the SIM card used to send SMS messages. This API uses a promise to return the result. 320 321**System capability**: SystemCapability.Telephony.SmsMms 322 323**Return value** 324 325| Type | Description | 326| --------------- | ------------------------------------------------------------ | 327| Promise<number> | Promise used to return the result.<br>- **0**: card slot 1<br>- **1**: card slot 2| 328 329**Example** 330 331```ts 332import sms from '@ohos.telephony.sms'; 333import { BusinessError } from '@ohos.base'; 334 335sms.getDefaultSmsSlotId().then((data: number) => { 336 console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); 337}).catch((err: BusinessError) => { 338 console.error(`getDefaultSmsSlotId failed, promise: err->${JSON.stringify(err)}`); 339}); 340``` 341 342## sms.hasSmsCapability<sup>7+</sup> 343 344hasSmsCapability\(\): boolean 345 346Checks whether the current device can send and receive SMS messages. This API works in synchronous mode. 347 348**System capability**: SystemCapability.Telephony.SmsMms 349 350**Return value** 351 352| Type | Description | 353| ------- | ------------------------------------------------------------ | 354| boolean | - **true**: The device can send and receive SMS messages.<br>- **false**: The device cannot send or receive SMS messages.| 355 356```ts 357import sms from '@ohos.telephony.sms'; 358 359let result = sms.hasSmsCapability(); 360console.log(`hasSmsCapability: ${JSON.stringify(result)}`); 361``` 362 363## sms.getDefaultSmsSimId<sup>10+</sup> 364 365getDefaultSmsSimId\(callback: AsyncCallback<number>\): void 366 367Obtains the default ID of the SIM card used to send SMS messages. This API uses an asynchronous callback to return the result. 368 369**System capability**: SystemCapability.Telephony.SmsMms 370 371**Parameters** 372 373| Name | Type | Mandatory| Description | 374| -------- | --------------------------- | ---- | ---------------------------------------- | 375| callback | AsyncCallback<number> | Yes | Callback used to return the result.<br>The return value is bound to the SIM card and increases from 1.| 376 377**Error codes** 378 379For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 380 381| ID| Error Message | 382| -------- | -------------------------------------------- | 383| 401 | Parameter error. | 384| 8300001 | Invalid parameter value. | 385| 8300002 | Operation failed. Cannot connect to service. | 386| 8300003 | System internal error. | 387| 8300004 | Do not have sim card. | 388| 8300999 | Unknown error code. | 389| 8301001 | SIM card is not activated. | 390 391**Example** 392 393```ts 394import sms from '@ohos.telephony.sms'; 395import { BusinessError } from '@ohos.base'; 396 397sms.getDefaultSmsSimId((err: BusinessError, data: number) => { 398 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 399}); 400``` 401 402 403## sms.getDefaultSmsSimId<sup>10+</sup> 404 405getDefaultSmsSimId\(\): Promise<number> 406 407Obtains the default ID of the SIM card used to send SMS messages. This API uses a promise to return the result. 408 409**System capability**: SystemCapability.Telephony.SmsMms 410 411**Return value** 412 413| Type | Description | 414| --------------- | ------------------------------------------------------------ | 415| Promise<number> | Promise used to return the result.<br>The return value is bound to the SIM card and increases from 1.| 416 417**Error codes** 418 419For details about the error codes, see[ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 420 421| ID| Error Message | 422| -------- | -------------------------------------------- | 423| 8300001 | Invalid parameter value. | 424| 8300002 | Operation failed. Cannot connect to service. | 425| 8300003 | System internal error. | 426| 8300004 | Do not have sim card. | 427| 8300999 | Unknown error code. | 428| 8301001 | SIM card is not activated. | 429 430**Example** 431 432```ts 433import sms from '@ohos.telephony.sms'; 434import { BusinessError } from '@ohos.base'; 435 436let promise = sms.getDefaultSmsSimId(); 437promise.then((data: number) => { 438 console.log(`getDefaultSmsSimId success, promise: data->${JSON.stringify(data)}`); 439}).catch((err: BusinessError) => { 440 console.error(`getDefaultSmsSimId failed, promise: err->${JSON.stringify(err)}`); 441}); 442``` 443 444 445## ShortMessage 446 447Defines an SMS message instance. 448 449**System capability**: SystemCapability.Telephony.SmsMms 450 451| Name | Type | Mandatory| Description | 452| ------------------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 453| 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. | 454| 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).| 455| 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.| 456| messageClass | [ShortMessageClass](#shortmessageclass) | Yes | Enumerates SMS message types. | 457| pdu | Array<number> | Yes | PDU in the SMS message. | 458| protocolId | number | Yes | Protocol identifier used for delivering the SMS message. | 459| scAddress | string | Yes | SMSC address. | 460| scTimestamp | number | Yes | SMSC timestamp. | 461| status | number | Yes | SMS message status sent by the SMSC in the **SMS-STATUS-REPORT** message.| 462| visibleMessageBody | string | Yes | SMS message body. | 463| visibleRawAddress | string | Yes | Sender address. | 464 465 466## ShortMessageClass 467 468Enumerates SMS message types. 469 470**System capability**: SystemCapability.Telephony.SmsMms 471 472| Name | Value | Description | 473| ---------------- | ---- | ---------------------------------------- | 474| UNKNOWN | 0 | Unknown type. | 475| INSTANT_MESSAGE | 1 | Instant message, which is displayed immediately after being received. | 476| OPTIONAL_MESSAGE | 2 | Message stored in the device or SIM card. | 477| SIM_MESSAGE | 3 | Message containing SIM card information, which is to be stored in the SIM card.| 478| FORWARD_MESSAGE | 4 | Message to be forwarded to another device. | 479 480 481## SendMessageOptions 482 483Provides the options (including callbacks) for sending SMS messages. For example, you can specify the SMS message type by the optional parameter **content**. 484 485**System capability**: SystemCapability.Telephony.SmsMms 486 487| Name | Type | Mandatory| Description | 488| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 489| slotId | number | Yes | Slot ID of the SIM card used for sending SMS messages. <br>- **0**: card slot 1<br>- **1**: card slot 2 | 490| destinationHost | string | Yes | Destination address of the SMS message. | 491| 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.| 492| serviceCenter | string | No | SMSC address. By default, the SMSC address in the SIM card is used. | 493| destinationPort | number | No | Destination port of the SMS message. This field is mandatory only for a data message. Otherwise, it is optional. | 494| sendCallback | AsyncCallback<[ISendShortMessageCallback](#isendshortmessagecallback)> | No | Callback used to return the SMS message sending result. For details, see [ISendShortMessageCallback](#isendshortmessagecallback).| 495| deliveryCallback | AsyncCallback<[IDeliveryShortMessageCallback](#ideliveryshortmessagecallback)> | No | Callback used to return the SMS message delivery report. For details, see [IDeliveryShortMessageCallback](#ideliveryshortmessagecallback).| 496 497 498 499## ISendShortMessageCallback 500 501Provides 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. 502 503**System capability**: SystemCapability.Telephony.SmsMms 504 505| Name | Type | Mandatory| Description | 506| ---------- | ------------------------------- | ---- | ----------------------------------------------------------------------------------------- | 507| 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**.| 508| result | [SendSmsResult](#sendsmsresult) | Yes | SMS message sending result. | 509| url | string | Yes | URI for storing the sent SMS message. | 510 511 512## IDeliveryShortMessageCallback 513 514Provides the callback for the SMS message delivery report. 515 516**System capability**: SystemCapability.Telephony.SmsMms 517 518| Name| Type | Mandatory| Description | 519| ---- | ------------------- | ---- | -------------- | 520| pdu | Array<number> | Yes | SMS message delivery report.| 521 522 523## SendSmsResult 524 525Enumerates SMS message sending results. 526 527**System capability**: SystemCapability.Telephony.SmsMms 528 529| Name | Value | Description | 530| ------------------------------------ | ---- | ------------------------------------------------------ | 531| SEND_SMS_SUCCESS | 0 | The SMS message is sent successfully. | 532| SEND_SMS_FAILURE_UNKNOWN | 1 | Failed to send the SMS message due to an unknown reason. | 533| SEND_SMS_FAILURE_RADIO_OFF | 2 | Failed to send the SMS message because the modem is shut down. | 534| 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.| 535