Short Message Service:Call the SMS API

Before you begin

Complete these preparations:

1. Create an account and complete enterprise identity verification: SMS requires an enterprise account. Complete enterprise identity verification.

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

3. Purchase a resource package: SMS uses prepaid resource packages by default. Purchase a resource package before use.

   • Add a credit card or PayPal account to your Alibaba Cloud account.

   • Choose a package based on your destinations and package specifications. To use pay-as-you-go billing, 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. Compliance requirements vary by destination. Complete the required procedures:

   • 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 provides an interactive interface for debugging API calls with real-time response previews, parameter validation, and multi-language sample code generation.

Click the Test button on any API reference page to open OpenAPI Explorer.

Integrate the SMS SDK

Use the official SDK to call the SMS API. This example calls SendMessageToGlobe with the Java SDK. For other languages, see the SDK reference.

1. Verify Java environment: Java 8 or later is required. For instructions, see Set up a Java development environment on Windows.

2. Install the SDK: Add a Maven dependency to your project.

   Add the following to your pom.xml within the <dependencies> tag. Replace the-latest-version with the latest version number, then reload 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: Call SendMessageToGlobe 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: A successful call returns output similar to the following:

   {
     "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

Receive delivery reports and user replies by setting up a Simple Message Queue (formerly MNS) consumer or a webhook endpoint for batched HTTP pushes. This enables delivery monitoring and two-way communication.

For more information, see Configure delivery receipts.

References

• API overview: Covers API operations, parameters, and limits.

• International error codes: Lists error codes returned by API calls or delivery receipts, with solutions.

• Get started with SMS API: Covers environment setup, calling process, and sample code.

Video tutorial

How to activate SMS.