All Products
Search

This Product

    Short Message Service:Get started with the SMS API

    Document Center

    Short Message Service:Get started with the SMS API

    Last Updated:Jan 10, 2025

    Alibaba Cloud SMS provides SDKs to help you use the SMS API.

    This topic takes the SendMessageToGlobe API operation as an example to walk you through the SMS API. Workflow:

    Note

    • If you are familiar with OpenAPI Explorer, you can refer to the API documentation and call API operations.

    • We recommend that you call API operations through SMS SDKs. For information about how to use custom encapsulated requests to call API operations, see Request syntax and signature method V3.

    Preparations

    Item

    Description

    References

    Signature

    Submit the signature for approval and obtain the signature name.

    Signature specifications

    Message template

    Submit the message template for approval and obtain the template code.

    Message template specifications

    User permissions

    Note

    We recommend that you grant permissions to a RAM user and use the RAM user to make API calls and perform daily O&M.

    Make sure that the RAM user that you want to use to call the API has the permissions on SMS:

    • AliyunDysmsFullAccess: grants the management permissions on SMS.

    • AliyunDysmsReadOnlyAccess: grants the read-only permissions on SMS.

    For more information about how to create a custom policy, see RAM authorization.

    Create a RAM user

    Grant permissions to a RAM user

    AccessKey ID

    To view the AccessKey ID of the RAM user, go to the Users page of the RAM console and click the name of the RAM user.

    Create an AccessKey pair

    AccessKey secret

    You can only view and record an AccessKey secret when creating it. Otherwise, you must create a new AccessKey pair.

    Create a RAM user and grant permissions to it

    1. Create a RAM user and an AccessKey pair

      Go to the Create User page of the Resource Access Management (RAM) console, specify a RAM username, set the Access Mode parameter to Using permanent AccessKey to access, and then click OK. After the RAM user is created, the AccessKey ID and AccessKey Secret are displayed for backup.

    2. Grant permissions to the RAM user

      Go to the Users page of the RAM console, find the RAM user, and click Add Permissions in the Actions column. In the Policy section of the panel that appears, search for and select the AliyunDysmsFullAccess policy, and then click Grant permissions.

    Deploy a development environment

    This topic uses Java as an example. For information about how to use SMS SDKs for other programming languages, see SDK reference.

    Deploy a Java environment

    The Java version must be later than 8. Check the Java version by running the following command in the terminal:

    java -version

    If you have not deployed a Java environment or the Java version is earlier than 8, see Build a Java development environment on Windows.

    Configure the SDK

    You can install the SDK through Maven dependencies. 

    <dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>dysmsapi20180501</artifactId>
  <version>1.0.10</version>
</dependency>

    Initialize the client

    Alibaba Cloud SDKs support multiple access credentials, such as AccessKey pairs and Security Token Service (STS) tokens, to initialize clients. For more information, see Manage access credentials. In this example, an AccessKey pair is used to initialize the client.

    Configure an AccessKey pair

    To prevent the AccessKey pair from being leaked due to hard-coding, you must configure environment variables to obtain an AccessKey pair. For more information about how to configure environment variables, see Configure environment variables in Linux, macOS, and Windows.

    In this example, the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET are used. Sample code:

    Config config = new Config()
        // Make sure that the environment variables are configured for code execution.
        .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
        .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    Note

    The System.getenv() method obtains system environment variables. You need to enter the variable names. Do not directly enter the AccessKey information.

    Configure the endpoint

    The following code configures the endpoint. Replace the endpoint based on the region. For more information, see Endpoints. 

    config.endpoint = "dysmsapi.ap-southeast-1.aliyuncs.com";

    Call an API operation

    Construct an API request

    Construct an API request and specify parameters based on your business requirements.

    Note

    The request object is named in the {API name}Request format. For example, the request object of the SendSms operation is SendSmsRequest. 

    SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
            .setTo("<YOUR_VALUE>")
            .setMessage("<YOUR_VALUE>");

    Send an API request

    Use the SendMessageToGlobe operation to send an API request.

    Note

    The response object is named in the {API name}Response format. For example, the response object of the SendSms operation is SendSmsResponse. 

    SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);

    Sample code

    Sample code:

    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 environment variable ALIBABA_CLOUD_ACCESS_KEY_ID is configured. 
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Configure the AccessKey secret. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET is configured. 
                .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 client
        Client client = Sample.createClient();

        // Construct the request object and specify the request parameters
        SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
                .setTo("<YOUR_VALUE>")
                .setMessage("<YOUR_VALUE>");

        // Obtain the response object
        SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);

        // Response body and headers
        System.out.println(toJSONString(sendSmsResponse));
    }
}

    FAQ

    How do I view the AccessKey ID and AccessKey secret?

    You can only view and record an AccessKey secret when creating it. Otherwise, you must create a new AccessKey pair.

    How do I encapsulate an HTTP request and use the curl command or Postman to call API operations?

    Alibaba Cloud SDKs have encapsulated the signature, timeout, and retry configurations. We recommend that you use Alibaba Cloud SDKs to reduce development costs. For information about how to encapsulate a request for API testing, see Request syntax and signature method V3.

    What to do next