• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# SMS Service Development
2
3## When to Use
4
5The Short Messaging Service (SMS) module provides basic SMS management functions. You can create and send SMS messages, and obtain the ID of the default SIM card used to send and receive SMS messages. Besides, you can obtain and set the SMSC address, and check whether the current device can send and receive SMS messages.
6
7Typical development scenarios are as follows:
8
9- On web pages:
10  - The **Send Message** button is displayed when users open a web page. After the user taps the button, the SMS application is started, and the user can then enter the recipient number and SMS message content to send an SMS message.
11- On applications:
12  - When a user taps the **Send Message** button on a mobile application, the application calls the system function to start the SMS application, and the user can then enter the recipient number and SMS message content to send an SMS message.
13
14## Basic Concepts
15
16- SMS
17
18  A service capable of SMS message storage and forwarding. It enables mobile phones to send and receive SMS messages. The content of the SMS message can be text, digits, or binary non-text data. The information about the sender is stored in the Short Message Service Center (SMSC) and forwarded to the recipient.
19- SMSC
20
21  An entity that relays, stores, or forwards SMS messages between base stations and mobile devices. It uses the GSM 03.40 protocol for sending SMS messages to or receiving SMS messages from mobile phones.
22- PDU
23
24  Protocol data unit, which uses the following encoding schemes to send and receive SMS messages: 7-bit, 8-bit, and UCS-2. 7-bit encoding is used to send common ASCII characters, 8-bit encoding to send data messages, and UCS-2 encoding to send Unicode characters.
25
26## Constraints
27
281. The SMS service is available only on standard-system devices.
292. An available SIM card must be present on the device, and the permission to send SMS messages must be granted.
30
31## Available APIs
32
33> **NOTE**
34> To maximize the application running efficiency, most APIs are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see the [API Reference](../reference/apis-telephony-kit/js-apis-sms.md).
35
36| Name                                                      | Description                                                   |
37| ------------------------------------------------------------ | ------------------------------------------------------- |
38| sendShortMessage(options: SendMessageOptions, callback: AsyncCallback\<void\>): void              | Sends text or data SMS messages. You need to request for the **ohos.permission.SEND_MESSAGES** permission, which is available only for system applications.     |
39| createMessage(pdu: Array\<number\>, specification: string, callback: AsyncCallback\<ShortMessage\>): void | Creates an SMS message instance based on the PDU and the specified SMS protocol.|
40| getDefaultSmsSlotId(callback: AsyncCallback\<number\>): void   | Obtains the ID of the default SIM card used to send SMS messages.                                               |
41| <!--DelRow-->setSmscAddr(slotId: number, smscAddr: string, callback: AsyncCallback\<void\>): void | Sets the SMSC address based on the specified slot ID.               |
42| <!--DelRow-->getSmscAddr(slotId: number, callback: AsyncCallback\<string>): void | Obtains the SMSC address based on the specified slot ID.                                 |
43
44<!--Del-->
45
46## Sending SMS Messages (for System Applications Only)
47
481. Declare the required permission:
49
50   - To send SMS messages, call the **sendShortMessage** API and declare the **ohos.permission.SEND\_MESSAGES** permission. The permission is of the **system\_basic** level.
51   - To set the SMSC address, call the** setSmscAddr** API and declare the **ohos.permission.SET\_TELEPHONY\_STATE** permission. The permission is of the **system\_basic** level.
52   - To obtain the SMSC address, call the** getSmscAddr** API and declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. The permission is of the **system\_basic** level.
53   Before requesting the permission, ensure that the [basic principles for using permissions](../security/AccessToken/app-permission-mgmt-overview.md#basic-principles-for-using-permissions) are met. Then, declare the required permission by referring to [Requesting Application Permissions](../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
542. Import the required modules.
55
563. Send an SMS message.
57
58```ts
59// Sample code
60import { sms } from '@kit.TelephonyKit';
61import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
62
63let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => {
64    console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
65}
66let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => {
67    console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
68}
69let slotId: number = 0;
70let content: string = 'Message content';
71let destinationHost: string = '+861xxxxxxxxxx';
72let serviceCenter: string = '+861xxxxxxxxxx';
73let destinationPort: number = 1000;
74let options: sms.SendMessageOptions = {slotId, content, destinationHost, serviceCenter, destinationPort, sendCallback, deliveryCallback};
75sms.sendShortMessage(options, (err: BusinessError) => {
76    console.error(`callback: err->${JSON.stringify(err)}`);
77});
78
79```
80
81<!--DelEnd-->
82
83## Redirecting to the SMS Message Editing Page of the Application
84
85The API for sending SMS messages can be called only after the required system permission is granted. For a third-party application, it also needs to implement the function of redirecting to the SMS editing page and obtaining the edited content and recipient number by calling the **startAbility** API.
86
87```ts
88// Sample code
89import { common, Want } from '@kit.AbilityKit';
90
91const MMS_BUNDLE_NAME = "com.ohos.mms";
92const MMS_ABILITY_NAME = "com.ohos.mms.MainAbility";
93const MMS_ENTITIES = "entity.system.home";
94
95export class Contact {
96    contactsName: string;
97    telephone: number;
98
99    constructor(contactsName: string, telephone: number) {
100        this.contactsName = contactsName;
101        this.telephone = telephone;
102    }
103}
104
105@Entry
106@Component
107struct JumpMessage {
108    private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
109
110    startMMSAbilityExplicit() {
111        // Complete the contact and number. You can query the contact name based on the phone number. Therefore, the phone number is mainly used in this mode.
112        let params: Array<Object> = [new Contact("Tom", 133XXXXXXXX)];
113
114        let want: Want = {
115            bundleName: "com.ohos.mms",
116            abilityName: "com.ohos.mms.MainAbility",
117            parameters: {
118                contactObjects: JSON.stringify(params),
119                pageFlag: "conversation",
120                // Enter the SMS message content.
121                content: "SMS message content"
122            }
123        };
124
125        this.context.startAbilityForResult(want).then((data) => {
126            console.log("Success" + JSON.stringify(data));
127        }).catch(() => {
128            console.error("error");
129        });
130    }
131
132    build() {
133        Row() {
134            Column() {
135                Button ('Send SMS')
136                  .onClick(() => {
137                      this.startMMSAbilityExplicit();
138                  })
139            }
140            .width('100%')
141        }
142        .height('100%')
143    }
144}
145
146```
147
148## Redirecting to the SMS Message Editing Page in SMS Mode
149
150### Scenario
151
152Through the SMS protocol, you can create a hyperlink pointing to the SMS recipient so that users can directly navigate to the SMS application through the hyperlink on a web page or an application. In addition, you can define the SMS message recipient and content in the `sms:` field to save the SMS message editing time.
153
154### SMS Protocol Format
155
156The standard SMS protocol format is as follows:
157
158```
159sms:106XXXXXXXXXX?body=SMS message content
160```
161
162+ `sms:`: SMS scheme, which is mandatory.
163+ `106XXXXXXXXXX`: recipient number, which is optional. If there are multiple addresses, separate them with commas (,).
164+ `?`: start declaration character of the SMS message content. This parameter is mandatory if the SMS message content is present.
165+ `body-value`: SMS message content, which is optional.
166
167### Developing a Caller Application
168
169#### On Web Pages
170
171Hyperlinks on web pages must comply with the SMS protocol. The sample code is as follows:
172
173```
174<a href="sms:106XXXXXXXXXX?body=%E5%8F%91%E9%80%81%E7%9F%AD%E4%BF%A1%E5%86%85%E5%AE%B9">Send Message</a>;
175```
176
177In actual development, replace the recipient number with the actual number. The SMS message content can be configured as required.
178
179#### On Applications
180
181Pass the sms string to the **uri** parameter. In the application, the context can be obtained through **this.getUIContext().getHostContext()** for a page and through **this.context** for an ability.
182
183```ts
184@Entry
185@Component
186struct Index {
187
188  build() {
189    Column() {
190      Button ('Send SMS')
191        .onClick(() => {
192          let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
193          let exampleUrl = "sms:106XXXXXXXXXX?body=%E5%8F%91%E9%80%81%E7%9F%AD%E4%BF%A1%E5%86%85%E5%AE%B9";
194
195          let want: Want = {
196              bundleName: 'com.ohos.mms',
197              action: 'ohos.want.action.viewData',
198              uri:exampleUrl,
199            }
200
201          context.startAbility(want).then((data) => {
202              console.log("Success" + JSON.stringify(data));
203          }).catch(() => {
204              console.error("error");
205          });
206
207        })
208    }
209  }
210}
211```
212