FAQ about using the Short Message Service API and SDK.-Short Message Service(SMS)-阿里云帮助中心

Frequently asked questions
AccessKey and RAM user questions
Preparation questions
API call and return value questions

Why can't I view my RAM user's AccessKey secret again in the Alibaba Cloud Management Console?

A Resource Access Management (RAM) user's AccessKey secret is displayed only when you create an AccessKey. You cannot view it after creation. After you create an AccessKey, save the AccessKey secret promptly and securely. For more information, see View the AccessKey information of a RAM user.

Can I use an AccessKey to call SMS API operations?

An AccessKey is associated with an Alibaba Cloud account and is not tied to a specific Alibaba Cloud product.

If you use the AccessKey of a RAM user, you can use it to call the API operations of the products for which the RAM user is granted permissions. Go to the Users page in the RAM console to grant permissions to the account. For more information, see RAM users.

Why does the international SMS API return a ServiceUnavailable error?

If a call to an international SMS API operation returns a ServiceUnavailable error, you may have used the domain name or template for domestic SMS.

The domain name for domestic SMS is dysmsapi.aliyuncs.com. The domain name for international SMS is dysmsapi.ap-southeast-1.aliyuncs.com. Also, make sure to use an international SMS template to send the text message.

How do I configure and get a securityToken to initialize a client account using STS authentication for SMS?

Use a security token to configure and obtain a temporary identity.

What is the difference between the TotalCount field in the QuerySendDetails operation and the number of messages shown in the console?

The TotalCount field indicates the total number of text messages sent. This is the number of sending records found for the phone numbers you provided. The number of messages displayed on the Delivery Records page in the console is the number of messages after they are split based on SMS sending rules.

Can I see an example of how to generate a signature for SMS using RPC?

This signature is different from the signature used when Short Message Service sends a text message. This signature is used to ensure the secure use of the API. When you call an API operation, Alibaba Cloud uses the signature to authenticate each API request. For the specific steps and an example of how to generate a signature, see Signature example code.

What should I do if I get an 'access denied' error when calling an API operation from a public IP address?

Check if you can successfully ping and curl dysmsapi.aliyuncs.com from your server. Also, check if traffic is allowed on ports 80 and 443 of your server.

Why do I get the 'Specified parameter Version is not valid' error when sending a text message?

Reason: The API version number is incorrect. Confirm the version number of the API operation.

The API version number for Short Message Service is 2017-05-25. For more information, see Integration overview.

Why did my text message fail to send with a blacklist control error?

A blacklist control error means the recipient's phone number is on a blacklist. These numbers have previously unsubscribed or filed a complaint and cannot receive text messages with this content. Avoid sending messages to this number and try again with a different one.

Important

Before registration completes, messages may fail to send. Common error codes include the following:

PORT_NOT_REGISTERED: The port number used has not completed enterprise identity registration.
Carrier identity registration typically takes 5 to 7 business days. Recent observations show it may take 7 to 10 business days for some carriers. Carriers do not guarantee these timelines, and actual processing may take longer. Plan your business accordingly and apply for qualifications and signatures early. Reserve time for test sends to ensure sufficient time for identity registration before going live.

Does SMS support the ROA mechanism for HTTP requests?

If you cannot use an SDK to integrate with Short Message Service, you can use HTTP requests. Currently, HTTP requests support only the RPC style, not the ROA mechanism. For more information, see V3 request body & signature mechanism.

What is the purpose of the BizId parameter in SMS API operations?

BizId is the delivery receipt ID. For the same Alibaba Cloud account, each sending record has a different BizId. In rare cases, different Alibaba Cloud accounts may have the same BizId. The purpose of BizId is to query the specific delivery status using the BizId value when you call the QuerySendDetails operation.

Can my SMS service key be leaked?

Short Message Service uses an AccessKey to call API operations and send text messages. If you suspect your AccessKey has been leaked, generate a new one. Then, disable or delete the original AccessKey. Before you disable or delete the key, confirm that no services are using it. For more information, see Secure use of credentials.

Are the Alibaba Cloud server IP addresses for SMS API calls fixed?

The SMS API operations are exposed only through domain names, not fixed IP addresses. Use the global endpoint domain name dysmsapi.aliyuncs.com.

For more information about endpoints, see Endpoints.

What is the difference between an SMS AccessKey and a RAM user?

An AccessKey is an access key pair created for an Alibaba Cloud account. It is used to authenticate the account when you call Alibaba Cloud API operations. An Alibaba Cloud account can have multiple AccessKey pairs. A RAM user is a sub-account of an Alibaba Cloud account. A RAM user can be used only after being granted permissions by the root account. For more information, see RAM users and AccessKey.

How do I view my AccessKey for SMS?

You can view the AccessKey ID in the console. The AccessKey secret is displayed only when you create an AccessKey. You cannot view it after creation. After you create an AccessKey, save the AccessKey secret promptly and securely. For more information, see View the AccessKey information of a RAM user.

How do I handle the SmsContent.Illegal error when I submit a template?

When you submit a template for Short Message Service, you may receive an "Illegal template content" error with the error code "smscontentillegal". This is usually because the template content contains special symbols, square brackets, traditional characters, typos, or non-standard characters. Modify the template content according to the SMS template specifications and submit it again for review. If the error persists, check if your account has violated the user agreement or platform rules related to content control. For more information, see the Terms of Service.

Important

Short Message Service reserves the right to take legal action for any illegal activities, regulatory violations, or infringement on the rights of others. You must strictly adhere to all guidelines, enhance your business security, and send only compliant text messages.

Why did my text message fail to send with the error code `isv.SMS_TEST_NUMBER_LIMIT`?

The error isv.SMS_TEST_NUMBER_LIMIT means you can only send text messages to a bound test phone number. If you have bound the recipient's number but still receive this error, check the following causes and solutions:

Causes

The test phone number is not bound in the console, or the binding process is incomplete or not yet effective.
The phone number in the API call does not match the bound phone number.
If you encounter this error in the production environment, you may have confused the staging and production environments.

Solutions

To send a text message using the test feature, you must bind a test phone number.
Confirm that the binding operation is complete and has taken effect. System processing or synchronization may be delayed.
Check that the phone number specified in the API request or console call exactly matches the bound test phone number, including the country code and format.
Test signatures and templates, which are marked with a green "Test" label in the console, can only be sent to bound test numbers. Make sure you use non-test signatures and templates for official message sending.

For a complete list of error codes, causes, and solutions, see API error codes.

Can I call the SMS API operations from an internal network?

To call SMS operations, you must access the Alibaba Cloud domain name to send text messages. Your network environment must be able to access the Alibaba Cloud domain name. Public network access is required. For more information, see the SMS API documentation.
If your server has network restrictions, such as being on a private network, and you receive a "connection timeout" error, add the public endpoint dysmsapi.aliyuncs.com to your whitelist. If you still cannot send text messages, try adjusting your local firewall configuration or check if the connection timeout is set too high.

Do I need to add IP addresses to a whitelist to call SMS API operations?

The public endpoint for sending text messages is dysmsapi.aliyuncs.com. Port 80 is used for HTTP calls, and port 443 is used for HTTPS calls.

You do not need to report your IP address to Alibaba Cloud before you call SMS API operations. You only need to be able to ping dysmsapi.aliyuncs.com. The corresponding IP address range is not fixed and changes periodically. If you have a special network environment, adjust your security policy to allow traffic to this domain name.

How can I create a custom HTTP request and use `curl` or Postman to call an API operation?

The Alibaba Cloud SDKs encapsulate mechanisms such as signing, timeouts, and retries. We recommend that you use an SDK for integration to reduce development costs. To create your own requests for API testing, see V3 signature mechanism and SendSms request example.