API Documentation (Alibaba SMS)

Description

This document explains the Alibaba SMS service and the guidelines for integration through the API.

Credentials

There are two methods for signing in to the Alibaba console: the Alibaba Cloud account and the RAM user.

A Resource Access Management (RAM) user is a physical identity. You can create RAM users for an Alibaba Cloud account and authorize the RAM users to access different resources.

Login URL: https://account.alibabacloud.com/login/login.htm

Security Note: Never commit credentials to source control. Always retrieve credentials from the approved secret store (e.g., AWS Secrets Manager or Vault). Contact DevOps if you need access.

Alibaba Cloud Account

Email:    <request from DevOps or retrieve from the approved secret store>
Password: <request from DevOps or retrieve from the approved secret store>

RAM User

Email:    <request from DevOps or retrieve from the approved secret store>
Password: <request from DevOps or retrieve from the approved secret store>

API References

• Developer Reference – Short Message Service
• API Reference PDF

There are two methods for integrating with the Alibaba SMS service:

1. API or SDKs
2. SMS console

This diagram shows the flow of how to configure the SMS service:

The diagram illustrates the end-to-end flow from account setup through sender registration, template approval, and API integration for sending SMS messages.

Dialing Codes

Alibaba Cloud Short Message Service (SMS) is available in more than 200 countries and regions. A dialing code indicates the destination country or region to which you send messages.

See: Dialing codes – Short Message Service

Endpoints (Base URLs)

There are different endpoints and base URLs for each country.

See: API Endpoints reference

Test Messages

If you have not published your application or service, you can use the Alibaba Cloud SMS console to send test messages for specific countries.

See: Send a test message

For example, use a temporary number for testing SMS in Thailand: receive-smss.com/sms/66993592971

Error Codes

See: Error codes – Short Message Service

Common Error Scenarios

Authentication and Authorization

You can obtain the AccessKey ID and AccessKey secret on the AccessKey Management page in the Alibaba Cloud Management Console. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. Keep your AccessKey secret strictly confidential.

API Credentials

AccessKeyID:     <retrieve from the approved secret store>
AccessKeySecret: <retrieve from the approved secret store>

See: Signature method

Example: Sending an SMS via API

# Using the Alibaba Cloud CLI (aliyun)
aliyun dysmsapi SendMessageToGlobe \
  --To "66812345678" \
  --Message "Your booking is confirmed." \
  --Type "OTP"

Or using the Ruby SDK:

require 'alibabacloud-dysmsapi20180501'

client = Alibabacloud::Dysmsapi20180501::Client.new(
  Alibabacloud::OpenApi::Config.new(
    access_key_id:     ENV['ALIBABA_ACCESS_KEY_ID'],
    access_key_secret: ENV['ALIBABA_ACCESS_KEY_SECRET'],
    endpoint:          'dysmsapi.ap-southeast-1.aliyuncs.com'
  )
)

request = Alibabacloud::Dysmsapi20180501::SendMessageToGlobeRequest.new(
  to:      '66812345678',
  message: 'Your booking is confirmed.',
  type:    'OTP'
)

response = client.send_message_to_globe(request)

Sending the SMS

SendMessageToGlobe

We use the SendMessageToGlobe endpoint to send SMS through Alibaba SMS. SendMessageToGlobe is for sending messages to regions outside the Chinese mainland.

Before sending SMS, register the sender first. The Alibaba team will verify the submitted identity.

Submit sender registrations at: Sender ID registration

You cannot call the SendMessageToGlobe operation to send messages to the Chinese mainland.

See full documentation: SendMessageToGlobe – Short Message Service

Notes for Quota per Second (QPS)

You may call this operation up to 300 times per second. If the number of calls per second exceeds this limit, throttling will be triggered. This can potentially impact your business operations. Implement exponential backoff and retry logic to handle throttling gracefully.

QueryMessage

We use the QueryMessage endpoint to check SMS delivery status.

See: QueryMessage – Short Message Service

SMS Webhook

We can configure an MNS queue or HTTP URL to receive delivery receipts or MO messages.

1. MNS queues – Configure an MNS queue to receive delivery receipts from a specified region. After enabling MNS in the SMS console, call SMS SDKs to pull delivery receipts by message type and queue name.
2. HTTP URLs – Set up an HTTP URL to receive delivery receipts or MO messages. SMS uses HTTP POST to push receipts to the specified URL.

See: Configure delivery receipts

References

• aliyun Ruby gem