Short Message Service:Call the SMS API

Before you begin

Before calling the SMS API, complete the following preparations:

1. Create an account and complete enterprise identity verification: SMS is available only to enterprise accounts. You must complete enterprise identity verification.

2. Activate SMS: Log on to the SMS console and follow the prompts to activate the service.

3. Purchase a resource package: By default, SMS is billed via prepaid resource packages. Purchase a resource package before you use the service.

   • Ensure that a credit card or PayPal account is added to your Alibaba Cloud account.

   • Purchase a suitable package based on the destinations and package specifications. If you prefer the pay-as-you-go model, contact sales to enable it.

4. Set up development environment: This involves creating a RAM User, granting permissions, and obtaining an AccessKey pair. For details, see Configure credentials.

5. Carrier compliance requirements for sending messages vary by country and region. To ensure deliverability, complete all required procedures for your destinations:

   • To send messages to the Chinese mainland (Go China), create an SMS signature and message template. They must be approved before use.

   • To send messages to regions outside the Chinese mainland (Go Globe), check if the destination country or region requires sender ID registration.

Use OpenAPI Explorer

OpenAPI Explorer is an interactive tool for debugging API calls. It is ideal for developers who are new to Alibaba Cloud or prefer a visual interface. OpenAPI Explorer provides real-time response previews, automatic parameter validation, and generates multi-language sample code to streamline integration.

You can open OpenAPI Explorer by clicking the Test button on an API reference page.

Integrate the SMS SDK

The easiest and most reliable way to call the SMS API is using the official SDK. This example uses the Java SDK to call the SendMessageToGlobe operation. For other languages, see the SDK reference.

1. Check your Java environment: You must have Java 8 or later installed. For instructions, see Build a Java development environment in Windows.

2. Install the SDK: Install the SDK by configuring a Maven dependency.

   In your Maven project's pom.xml file, add the following dependency within the <dependencies> tag. Replace the-latest-version with the latest version number. After saving the file, reload your Maven dependencies.

   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>dysmsapi20180501</artifactId>
       <!-- Replace 'the-latest-version' with the latest version number: https://mvnrepository.com/artifact/com.aliyun/dysmsapi20180501 -->
       <version>the-latest-version</version>
   </dependency>

3. View the sample code: The following example shows how to call the SendMessageToGlobe operation by using the Java SDK. Fill in the parameters as indicated by the comments.

   package com.aliyun.sample;
   
   import com.aliyun.teaopenapi.models.Config;
   import com.aliyun.dysmsapi20180501.Client;
   import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest;
   import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeResponse;
   import static com.aliyun.teautil.Common.toJSONString;
   
   public class Sample {
       public static Client createClient() throws Exception {
           Config config = new Config()
                   // Configure the AccessKey ID. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is set.
                   .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                   // Configure the AccessKey secret. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is set.
                   .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
   
           // Configure the endpoint.
           config.endpoint = "dysmsapi.ap-southeast-1.aliyuncs.com";
   
           return new Client(config);
       }
   
       public static void main(String[] args) throws Exception {
           // Initialize the request client.
           Client client = Sample.createClient();
   
           // Construct the request object. Fill in the parameter values.
           SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
                   .setTo("<YOUR_VALUE>")
                   .setMessage("<YOUR_VALUE>");
   
           // Get the response object.
           SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);
   
           // The response contains the body and headers from the server.
           System.out.println(toJSONString(sendSmsResponse));
       }
   }

4. You can also download the sample code and run it directly.

   1. On the Parameters tab, enter the required parameter values.

   2. On the SDK Sample Code tab on the right, select V2.0 for the SDK version and Java for the language, and then click Download Project to download the sample code package.

   3. After unzipping the package, open the project in your IDE. After the dependencies are loaded, open src/main/java/com/aliyun/sample/Sample.java.

5. Review the response: After the project runs, you will see output similar to the following sample response.

   {
     "headers": {
       "date": "Tue, 24 Oct 2023 07:47:17 GMT",
       "content-type": "application/json;charset=utf-8",
       "content-length": "263",
       "connection": "keep-alive",
       "keep-alive": "timeout=25",
       "access-control-allow-origin": "*",
       "access-control-expose-headers": "*",
       "x-acs-request-id": "97B1D7B6-F2F6-3A50-97BC-A90B43EC962F",
       "x-acs-trace-id": "29c11fe4c778b74774d5f5602f0e7975",
       "etag": "2a+mcDRTDkXqx9VF7b6U57Q3"
     },
     "statusCode": 200,
     "body": {
       "ResponseCode": "OK",
       "NumberDetail": {
       "Region": "Taiwan",
       "Country": "Taiwan, Province of China",
       "Carrier": "FarEasTone"
     },
       "RequestId": "97B1D7B6-F2F6-3A50-97BC-A90B43EC962F",
       "Segments": "1",
       "ResponseDescription": "OK",
       "To": "88691567****",
       "MessageId": "191921698133637273"
     }
   }

Delivery receipts

To receive delivery reports and user replies, you can set up a consumer for Simple Message Queue (formerly MNS) or provide a webhook endpoint to receive batched HTTP pushes. This allows you to monitor delivery success rates and enable two-way communication in your applications.

For more information, see Configure delivery receipts.

References

• API overview: Describes the API operations, including usage notes, parameter details, and limits.

• Error codes: Lists the error codes that may be returned when calling an API or receiving a delivery receipt and provides solutions.

• Get started with SMS API: Provides detailed information about environment configuration, the process for making calls, and related sample code.

Video tutorial

Video tutorial on how to activate SMS.